diff --git a/README.rst b/README.rst index 24c3f991..374cb6d0 100644 --- a/README.rst +++ b/README.rst @@ -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 `_. + +Documentation +************* + +A documentation for ``xmlsec`` can be found at `xmlsec.readthedocs.io `_. -****** Usage -****** +***** -Check the `examples `_ to see various examples of signing and verifying using the library. +Check the `examples `_ 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) ^^^^^^^^^^^^^^ @@ -44,15 +52,15 @@ 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) @@ -60,162 +68,149 @@ 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 `_ (see build`s artifacts). -#. Install wheel +Windows +^^^^^^^ - .. code-block:: bash - - pip install - - -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 `_ 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 `_. - The `mkvirtualenv` command is available from `virtualenvwrapper` which - can be installed by following `link `_ +#. 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 `_ 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 `_ for more information. diff --git a/doc/source/install.rst b/doc/source/install.rst index 57107c75..834b9acb 100644 --- a/doc/source/install.rst +++ b/doc/source/install.rst @@ -1,67 +1,89 @@ -Install ------------ +Installation +============ -Linux (Debian) -^^^^^^^^^^^^^^ +``xmlsec`` is available on PyPI: .. code-block:: bash - apt-get install libxml2-dev libxmlsec1-dev libxmlsec1-openssl - pip install xmlsec + pip install xmlsec +Depending on your OS, you may need to install the required native +libraries first: -Note: There is no required version of libxml2 for ubuntu precise, -so need to download and install it manually. +Linux (Debian) +-------------- .. 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 + apt-get install libxml2-dev libxmlsec1-dev libxmlsec1-openssl + +.. 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 Linux (CentOS) -^^^^^^^^^^^^^^ +-------------- .. code-block:: bash - yum install libxml2-devel xmlsec1-devel xmlsec1-openssl-devel libtool-ltdl-devel - pip install xmlsec + yum install libxml2-devel xmlsec1-devel xmlsec1-openssl-devel libtool-ltdl-devel + + +Linux (Fedora) +-------------- + +.. code-block:: bash + + dnf install libxml2-devel xmlsec1-devel xmlsec1-openssl-devel libtool-ltdl-devel Mac -^^^ +--- .. code-block:: bash - xcode-select --install - brew upgrade - brew install libxml2 libxmlsec1 pkg-config - pip install xmlsec + xcode-select --install + brew upgrade + brew install libxml2 libxmlsec1 pkg-config +Alpine +------ -Windows (Wheel) -^^^^^^^^^^^^^^^ +.. code-block:: bash -#. Download appropriate binary wheels from `appveyor `_ (see build`s artifacts). + apk add build-base libressl libffi-dev libressl-dev libxslt-dev libxml2-dev xmlsec-dev xmlsec -#. Install downloaded wheel - .. code-block:: bash +Troubleshooting +*************** - pip install +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 (pip) -^^^^^^^^^^^^^ -#. Configure build environment, see `wiki.python.org `_ for more details. +Windows +------- + +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: -#. Install from pip +#. Configure build environment, see `wiki.python.org `_ for more details. - .. code-block:: bash +#. Install from source dist: - pip install xmlsec + .. code-block:: bash + pip install xmlsec --no-binary=xmlsec diff --git a/setup.py b/setup.py index 962114cd..68542db8 100644 --- a/setup.py +++ b/setup.py @@ -1,3 +1,4 @@ +import io import multiprocessing import os import subprocess @@ -11,7 +12,6 @@ from setuptools.command.build_ext import build_ext as build_ext_orig if sys.version_info >= (3, 4): - from pathlib import Path from urllib.request import urlcleanup, urljoin, urlretrieve else: from urllib import urlcleanup, urlretrieve @@ -397,6 +397,8 @@ def prepare_static_build_linux(self): if sys.version_info >= (3, 4): + from pathlib import Path + src_root = Path(__file__).parent / 'src' sources = [str(p.absolute()) for p in src_root.rglob('*.c')] else: @@ -415,12 +417,18 @@ def prepare_static_build_linux(self): setup_reqs.append('pathlib2') +with io.open('README.rst', encoding='utf-8') as f: + long_desc = f.read() + + setup( name='xmlsec', use_scm_version=True, description='Python bindings for the XML Security Library', + long_description=long_desc, ext_modules=[pyxmlsec], cmdclass={'build_ext': build_ext}, + python_requires='>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*', setup_requires=setup_reqs, install_requires=['lxml>=3.8'], author="Bulat Gaifullin",