Skip to content

Readme overhaul #136

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
May 20, 2020
Merged

Readme overhaul #136

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9f88cab
fix rst formatting issues in readme, remove python compat section, ad…
hoefling May 20, 2020
5472a79
include readme in package metadata
hoefling May 20, 2020
7b3af14
restrict supported python versions through package metadata
hoefling May 20, 2020
825f2c6
update installation notes in docs
hoefling May 20, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
185 changes: 90 additions & 95 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,26 +15,34 @@ python-xmlsec
:target: https://xmlsec.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status

Python bindings for the XML Security Library.
Python bindings for the `XML Security Library <https://www.aleksey.com/xmlsec/>`_.

Documentation
*************

A documentation for ``xmlsec`` can be found at `xmlsec.readthedocs.io <https://xmlsec.readthedocs.io/>`_.

******
Usage
******
*****

Check the `examples <http://pythonhosted.org/xmlsec/examples.html>`_ to see various examples of signing and verifying using the library.
Check the `examples <https://xmlsec.readthedocs.io/en/latest/examples.html>`_ section in the documentation to see various examples of signing and verifying using the library.

************
Requirements
************
- libxml2 >= 2.9.1
- libxmlsec1 >= 1.2.14
- ``libxml2 >= 2.9.1``
- ``libxmlsec1 >= 1.2.18``

*******
Install
*******

Pre-Install
-----------
``xmlsec`` is available on PyPI:

.. code-block:: bash

pip install xmlsec

Depending on your OS, you may need to install the required native
libraries first:

Linux (Debian)
^^^^^^^^^^^^^^
Expand All @@ -44,178 +52,165 @@ Linux (Debian)
apt-get install libxml2-dev libxmlsec1-dev libxmlsec1-openssl


Note: There is no required version of libxml2 for ubuntu precise,
so need to download and install it manually.
Note: There is no required version of LibXML2 for Ubuntu Precise,
so you need to download and install it manually.

.. code-block:: bash

wget http://xmlsoft.org/sources/libxml2-2.9.1.tar.gz
tar -xvf libxml2-2.9.1.tar.gz
cd libxml2-2.9.1
./configure && make && make install
wget http://xmlsoft.org/sources/libxml2-2.9.1.tar.gz
tar -xvf libxml2-2.9.1.tar.gz
cd libxml2-2.9.1
./configure && make && make install


Linux (CentOS)
^^^^^^^^^^^^^^

.. code-block:: bash

yum install libxml2-devel xmlsec1-devel xmlsec1-openssl-devel libtool-ltdl-devel
yum install libxml2-devel xmlsec1-devel xmlsec1-openssl-devel libtool-ltdl-devel


Mac
^^^
Linux (Fedora)
^^^^^^^^^^^^^^

.. code-block:: bash

brew install libxml2 libxmlsec1 pkg-config
dnf install libxml2-devel xmlsec1-devel xmlsec1-openssl-devel libtool-ltdl-devel


Alpine
^^^^^^
Mac
^^^

.. code-block:: bash

apk add build-base libressl libffi-dev libressl-dev libxslt-dev libxml2-dev xmlsec-dev xmlsec
brew install libxml2 libxmlsec1 pkg-config


Automated
---------
1. **xmlsec** can be installed through `easy_install` or `pip`.
Alpine
^^^^^^

.. code-block:: bash

pip install xmlsec
apk add build-base libressl libffi-dev libressl-dev libxslt-dev libxml2-dev xmlsec-dev xmlsec


Troubleshooting
***************

Mac
^^^

If you get any fatal errors about missing .h files, update your C_INCLUDE_PATH environment variable to
include the appropriate files from the libxml2 and libxmlsec1 libraries.


Windows (Wheel)
^^^^^^^^^^^^^^^
If you get any fatal errors about missing ``.h`` files, update your
``C_INCLUDE_PATH`` environment variable to include the appropriate
files from the ``libxml2`` and ``libxmlsec1`` libraries.

#. Download appropriate binary wheel from `ci.appveyor.com <https://ci.appveyor.com/project/bgaifullin/python-xmlsec>`_ (see build`s artifacts).

#. Install wheel
Windows
^^^^^^^

.. code-block:: bash

pip install <wheel filename>


Windows (pip)
^^^^^^^^^^^^^
Starting with 1.3.7, prebuilt wheels are available for Windows,
so running ``pip install xmlsec`` should suffice. If you want
to build from source:

#. Configure build environment, see `wiki.python.org <https://wiki.python.org/moin/WindowsCompilers>`_ for more details.

#. Install from pip
#. Install from source dist:

.. code-block:: bash
.. code-block:: bash

pip install xmlsec
pip install xmlsec --no-binary=xmlsec


Manual
------
Building from source
********************

#. Clone the **xmlsec** repository to your local computer.
#. Clone the ``xmlsec`` source code repository to your local computer.

.. code-block:: bash
.. code-block:: bash

git clone git://github.com/mehcode/python-xmlsec.git
git clone https://github.com/mehcode/python-xmlsec.git

#. Change into the **xmlsec** root directory.
#. Change into the ``python-xmlsec`` root directory.

.. code-block:: bash
.. code-block:: bash

cd /path/to/xmlsec
cd /path/to/xmlsec


#. Install the project and all its dependencies using `pip`.
#. Install the project and all its dependencies using ``pip``.

.. code-block:: bash
.. code-block:: bash

pip install .
pip install .


************
Contributing
************

Setting up your environment
---------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^

#. Follow steps 1 and 2 of the `manual installation instructions <#manual>`_.
#. Follow steps 1 and 2 of the `manual installation instructions <#building-from-source>`_.


#. Initialize a virtual environment to develop in.
This is done so as to ensure every contributor is working with
close-to-identicial versions of packages.

.. code-block:: bash
.. code-block:: bash

mkvirtualenv xmlsec
mkvirtualenv xmlsec

The ``mkvirtualenv`` command is available from ``virtualenvwrapper`` package which can be installed by following `link <http://virtualenvwrapper.readthedocs.org/en/latest/install.html#basic-installation>`_.

The `mkvirtualenv` command is available from `virtualenvwrapper` which
can be installed by following `link <http://virtualenvwrapper.readthedocs.org/en/latest/install.html#basic-installation>`_
#. Activate the created virtual environment:

#. Install **xmlsec** in development mode with testing enabled.
.. code-block:: bash

workon xmlsec

#. Install ``xmlsec`` in development mode with testing enabled.
This will download all dependencies required for running the unit tests.

.. code-block:: bash
.. code-block:: bash

pip install -r requirements-test.txt
pip install -e "."
pip install -r requirements-test.txt
pip install -e "."


Running the test suite
----------------------
^^^^^^^^^^^^^^^^^^^^^^

#. [Set up your environment](#setting-up-your-environment).
#. `Set up your environment <#setting-up-your-environment>`_.

#. Run the unit tests.

.. code-block:: bash
.. code-block:: bash

py.test tests
pytest tests

#. Tests configuration
Env variable **PYXMLSEC_TEST_ITERATIONS** specifies number of test iterations to detect memory leaks.

Reporting a issue
-----------------
Please attach the output of following information:
version of python-xmlsec
version of libxmlsec1
version of libxml2

output from command:
Env variable ``PYXMLSEC_TEST_ITERATIONS`` specifies number of
test iterations to detect memory leaks.

.. code-block:: bash

pkg-config --cflags xmlsec1
Reporting an issue
^^^^^^^^^^^^^^^^^^

Please attach the output of following information:

******************
Versions of python
******************
* version of ``xmlsec``
* version of ``libxmlsec1``
* version of ``libxml2``
* output from the command

The following versions of python is supported:
.. code-block:: bash

- python2.7
- python3.4
- python3.5 (required libxmlsec1 >= 1.2.18 and libxml2 >= 2.9.1)
- python3.6 (required libxmlsec1 >= 1.2.18 and libxml2 >= 2.9.1)
- python3.7 (required libxmlsec1 >= 1.2.18 and libxml2 >= 2.9.1)
pkg-config --cflags xmlsec1

*******
License
*******

Unless otherwise noted, all files contained within this project are liensed under the MIT opensource license.
See the included file LICENSE or visit `opensource.org <http://opensource.org/licenses/MIT>`_ for more information.
Unless otherwise noted, all files contained within this project are licensed under the MIT opensource license.
See the included ``LICENSE`` file or visit `opensource.org <http://opensource.org/licenses/MIT>`_ for more information.
Loading