1.. _development:
2
3Development
4===========
5
6The following details the tools needed to contribute to the
7development of Pyrseas.  If you have any doubts or questions, please
8open an issue on GitHub (https://github.com/perseas/Pyrseas/issues).
9In addition, see *Version Control* below on how to set up a GitHub
10account to participate in development.
11
12Requirements
13------------
14
15- Git
16
17- Python
18
19- Postgres
20
21- Psycopg2
22
23- PyYAML
24
25- PgDbConn
26
27- Tox
28
29Version Control
30---------------
31
32Pyrseas uses `Git <https://git-scm.com/>`_ to control changes to its
33source code. As mentioned under :ref:`download`, the master Git
34`repository <https://github.com/perseas/Pyrseas>`_ is located at GitHub.
35
36To install Git, either `download and install
37<https://git-scm.com/download>`_ the latest stable release for your
38platform or follow the `Pro Git` `installation instructions
39<https://git-scm.com/book/en/Getting-Started-Installing-Git>`_.  For
40most Linux users, ``apt-get`` or ``yum`` (depending on Linux flavor)
41will be the simplest means to install the ``git-core`` package.  For
42Windows, downloading the installer and selecting ``Git Bash`` gives
43you not only Git but a Bash shell, which is handy if you're coming
44from a Linux/Unix background.
45
46Once Git is installed, change to a suitable directory and clone the
47master repository::
48
49 git clone git://github.com/perseas/Pyrseas.git
50
51or::
52
53 git clone https://github.com/perseas/Pyrseas.git
54
55To be able to create a fork on GitHub, open an issue or participate in
56Pyrseas development, you'll first have to `create a GitHub account
57<https://github.com/join>`_.
58
59Programming Language
60--------------------
61
62To contribute to Pyrseas, you need at least one version of `Python
63<https://www.python.org>`_.  You can develop using Python 3, but since
64we will continue supporting Python 2 until its end-of-life, you can
65also install Python 2.7 in addition to Python 3.7 or 3.6.
66
67If Python is not already available on your machine, either `download
68and install one or both <https://www.python.org/downloads/>`_ of the
69production releases for your platform, follow the applicable
70installation instructions given in `The Hitchhiker’s Guide to Python!
71<http://docs.python-guide.org/en/latest/>`_ or install it from your
72platform's package management system.
73
74Database Installation
75---------------------
76
77To participate in Pyrseas development, you'll also need one or more
78installations of `Postgres <https://www.postgresql.org>`_, versions
7911, 10, 9.6, 9.5 or 9.4.  If you only have limited space, it is
80preferable to install one of the latest two versions.
81
82The versions can be obtained as binary packages or installers from the
83`Postgres.org website <https://www.postgresql.org/download/>`_.  The
84site also includes instructions for installing from package management
85systems or building it from source.
86
87To access Postgres from Python, you have to install the `Psycopg
88<http://initd.org/psycopg/>`_ adapter. You can either follow the
89instructions in `Psycopg's site
90<http://initd.org/psycopg/docs/install.html>`_, or install it from
91your package management system.  Note that if you install both Python
922 and 3, you will have to install two packages, e.g.,
93``python-psycopg2`` and ``python3-psycopg2``.
94
95Other Libraries and Tools
96-------------------------
97
98The ``dbtoyaml`` and ``yamltodb`` utilities use the `PyYAML
99<http://pyyaml.org/wiki/PyYAML>`_ library.  You can install it from
100the PyYAML site, or possibly from your package management system.  For
101Windows 64-bit, please read the note under :ref:`installer`.
102
103The utilities also rely on `PgDbConn
104<https://github.com/perseas/pgdbconn>`_, an offshoot of the Perseas
105project that provides a thin, object-oriented layer over Psycopg2.
106You can install it from `PyPI <https://pypi.org/project/pgdbconn/>`_.
107
108To easily run the Pyrseas tests against various Python/Postgres
109version combinations, you will need `pytest
110<https://pytest.readthedocs.io/en/latest/>`_ and `Tox
111<https://tox.readthedocs.io/en/latest/>`_.  Please refer to
112:ref:`testing` for more information.
113