From 4327e41f19ac9cd48c8fa008ec1e0dfc9a2fc1a4 Mon Sep 17 00:00:00 2001 From: Daniele Varrazzo Date: Sat, 5 Dec 2020 01:58:19 +0000 Subject: [PATCH] Installation and readme improvements --- README.rst | 67 +++++++++++++++++++++++++++++++++--------------- docs/install.rst | 65 ++++++++++++++++++++++++++++++++++------------ docs/usage.rst | 2 ++ 3 files changed, 97 insertions(+), 37 deletions(-) diff --git a/README.rst b/README.rst index dd1635ae4..e64d72403 100644 --- a/README.rst +++ b/README.rst @@ -3,42 +3,68 @@ psycopg3 -- PostgreSQL database adapter for Python psycopg3 is a modern implementation of a PostgreSQL adapter for Python. -The package is split in different parts, with different requirements. -- The pure python package only depends on the **libpq**, the PostgreSQL client - library. The code is in the ``psycopg3`` directory. +Installation +------------ -- The optional C optimization: in order to build it requires the **libpq-dev** - packages, a C compiler and Cython. The code is in the ``psycopg3_c`` - directory. +The library is still in a development stage and is not available on PyPI in +the form of packages yet. You can install it directly `from the GitHub +project`__:: + $ pip install git+https://github.com/psycopg/psycopg3.git#subdirectory=psycopg3 + $ python3 + >>> import psycopg3 -Installation ------------- +.. __: https://github.com/psycopg/psycopg3 -The library is still in early development stage. If you want to try it out you -can install it from source using:: +You are required to have the ``libpq``, the PostgreSQL client library, already +installed in the system before using ``psycopg3``. On Debian system you can +obtain it by running:: - git clone https://github.com/psycopg/psycopg3.git - cd psycopg3 - python psycopg3/setup.py install # for the base Python package - python psycopg3_c/setup.py install # for the C extension module + sudo apt-get install libpq5 + +Please check your system's documentation for information about installing the +``libpq`` on your platform. Hacking ------- -You can create a local virtualenv and install there the dev and test -requirements. Feel free to adapt the following recipe if you follow a -different development pattern:: +In order to work on the ``psycopg3`` source code you should clone this +repository:: + + git clone https://github.com/psycopg/psycopg3.git + cd psycopg3 + +Please note that the repository contains the source code of several Python +packages: that's why you don't see a ``setup.py`` here. The packages may have +different requirements: + +- The ``psycopg3`` directory contains the pure python implementation of + ``psycopg3``. The package has only a runtime dependency on the ``libpq``, + the PostgreSQL client library, which should have been already installed in + your system. + +- The ``psycopg3_c`` directory contains an optimization module written in + C/Cython. In order to build it you will need a few development tools: please + look at `Local installation`__ in the docs for the details. + + .. __: https://www.psycopg.org/psycopg3/docs/install.html#local-installation + +You can create a local virtualenv and install there the packages `in +development mode`__, together with their development and testing +requirements:: python -m venv .venv source .venv/bin/activate - pip install -e ./psycopg3[dev,test] # for the base Python pacakge + pip install -e ./psycopg3[dev,test] # for the base Python package pip install -e ./psycopg3_c # for the C extension module -You can use tox to validate the code:: +.. __: https://pip.pypa.io/en/stable/reference/pip_install/#install-editable + +Now hack away! You can use tox to validate the code:: + pip install tox tox -p4 and to run the tests:: @@ -50,4 +76,5 @@ and to run the tests:: Please look at the commands definitions in the ``tox.ini`` files if you want to run some of them interactively: the dependency should be already in your -virtualenv. +virtualenv. Feel free to adapt these recipes if you follow a different +development pattern. diff --git a/docs/install.rst b/docs/install.rst index 45d631eaf..406678d89 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -3,6 +3,26 @@ Installation ============ +Installing the development state +-------------------------------- + +``psycopg3`` packages have not been released yet, but you can try it out +already by installing it `from the GitHub project`__: + +.. code:: bash + + $ pip install git+https://github.com/psycopg/psycopg3.git#subdirectory=psycopg3 + $ python3 + >>> import psycopg3 + +.. __: https://github.com/psycopg/psycopg3 + + +.. _binary-install: + +Binary installation +------------------- + .. warning:: `!psycopg3` is still in a development phase: packages haven't been @@ -16,10 +36,8 @@ Installation The following is how it will be *supposed* to work, once it is released... -Quick install -------------- - -The quickest way to start developing with psycopg3 is to run:: +The quickest way to start developing with psycopg3 is to install the binary +packages by running:: pip install psycopg3[binary] @@ -29,22 +47,33 @@ The above package should work in most situations. It **will not work** in some though: - the ``binary`` package doesn't work on Alpine Linux; -- the ``binary`` package is not advised in production. +- you have a newly released Python or Mac Os X version for which binary + packages are not ready yet. +In these case you should proceed to a :ref:`local installation +` or a :ref:`pure Python installation +`. -Proper installation -------------------- +.. seealso:: -.. admonition:: TODO + Did ``psycopg3`` install ok? Great! You can now move on to the :ref:`basic + module usage ` to learn how it works. - "proper" is scary... bettern name? + You can come back here if you the above method didn't work and you need a + way to install ``psycopg3`` past the basic one. -Proper install means obtaining a performing and maintainable library. The -library will include a performing C module and will be bound to the system -libpq, so that system upgrade of libraries will upgrade the library used by -``psycopg3``. -In order to perform a "proper" installation you need some prerequisites: +.. _local-installation: + +Local installation +------------------ + +A "Local installation" means obtaining a performing and maintainable library. +The library will include a performing C module and will be bound to the system +libraries (``libpq``, ``libssl``...) so that system upgrade of libraries will +upgrade the libraries used by ``psycopg3`` too. + +In order to perform a local installation you need some prerequisites: - a C compiler, - Python development headers (e.g. the python3-dev package). @@ -53,13 +82,15 @@ In order to perform a "proper" installation you need some prerequisites: You **must be able** to troubleshoot an extension build, for instance you must be able to read your compiler's error message. If you are not, please don't -try this and follow the `quick install`_ instead. +try this and follow the `binary installation`_ instead. If your build prerequisites are in place you can run:: pip install psycopg3[c] +.. _pure-python-installation: + Pure Python installation ------------------------ @@ -78,8 +109,8 @@ need:: sudo apt-get install libpq5 -If you are not able to fulfill this requirement please follow the `quick -install`_. +If you are not able to fulfill this requirement please follow the `binary +installation`_. diff --git a/docs/usage.rst b/docs/usage.rst index ede4a39c8..65a950558 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,5 +1,7 @@ .. currentmodule:: psycopg3 +.. _module-usage: + Basic module usage ================== -- 2.47.2