Building and developing pymssql¶
Required software¶
To build pymssql
you should have:
- Python >= 3.6 including development files.
Please research your OS usual software distribution channels,
e.g,
python-dev
orpython-devel
packages on Linux. - Cython -
to compile
pymssql
source files toC
. - setuptools -
for
setup.py
support. - setuptools_scm -
for extracting version information from
git
. - wheel - for building python wheels.
- FreeTDS >= 1.2 including development files.
Please research your OS usual software distribution channels,
e.g,
freetds-dev
orfreetds-devel
packages on Linux. - GNU gperf - a perfect hash function generator, needed for FreeTDS. On Windows prebuild version is available from Chocolatey.
- win-iconv
(Windows only) - developing
pymssql
on Windows also requires this library to build FreeTDS. - OpenSSL - If you need to connect to Azure make sure FreeTDS is built with SSL support. Please research your OS usual software distribution channels. On Windows one easy way is to get prebuild libraries from Chocolatey.
For testing the follwing is required:
- Microsoft SQL Server. One possibility is to use official docker images for Microsoft SQL Server on Linux available here.
- pytest - to run the tests.
- pytest-timeout - for limiting long running tests.
- psutil - for memory monitoring.
- gevent (optional) - for async tests.
- Sqlalchemy - (optional) - for basic Sqlalchemy testing.
To build documentation Sphinx and sphinx-rtd-theme are also needed.
Windows¶
In addition to the requirements above when developing pymssql
on the Windows
platform you will need these additional tools installed:
- Visual Studio C++ Compiler Tools, see Python documentation for instructions on what components to install.
- Cmake for building FreeTDS and win-iconv.
- curl - for downloading FreeTDS and win-iconv.
Note
If Windows computer is not readily available then virtual machine from Microsoft could be used.
Building pymssql
wheel¶
It is recommended to use python virtual environment for building pymssql
:
python3 -m venv <path_to_pve>
if using bash
:
source <path_to_pve>/bin/activate
or if on Windows:
<path_to_pve>/scripts/activate.bat
then install required python packages:
pip intall -U pip
pip install dev/requirements-dev.txt
If and now build wheel:
python3 setup.py bdist_wheel
or:
pip wheel .
Environment Variables¶
By default setup.py
links against OpenSSL if it is available,
links FreeTDS statically and looks for FreeTDS headers and libraries
in places standard for the OS, but
there are several environment variables for build customization:
- LINK_FREETDS_STATICALLY = [YES|NO|1|0|TRUE|FALSE]
- default - YES, defines if FreeTDS is linked statically or not.
- LINK_OPENSSL = [YES|NO|1|0|TRUE|FALSE]
- default - YES,
defines if
pymssql
is linked against OpenSSL. - PYMSSQL_FREETDS
- if defined, determines prefix of the FreeTDS installation.
- PYMSSQL_FREETDS_INCLUDEDIR
- if defined, alows to fine tune where to search for FreeTDS headers.
- PYMSSQL_FREETDS_LIBDIR
- if defined, alows to fine tune where to search for FreeTDS libraries.
Example:
PYMSSQL_FREETDS=/tmp/freetds python3 setup.py bdist_wheel
Building FreeTDS and pymssql
from scratch¶
If one wants to use some specific FreeTDS version then there is a script
dev/build.py
that downloads and builds required FreeTDS version sources
(and win-conv on Windows) and builds pymssql
wheel.
Run:
python dev/build.py --help
for supported options.
Testing¶
Danger
ALL DATA IN TESTING DBS WILL BE DELETED !!!!
You will need to install two additional packages for testing:
easy_install pytest SQLAlchemy
You should build the package with:
python setup.py develop
You need to setup a tests.cfg
file in tests/
with the correct DB
connection information for your environment:
cp tests/tests.cfg.tpl tests/tests.cfg
vim|emacs|notepad tests/tests.cfg
To run the tests:
cd tests # optional
py.test
Which will go through and run all the tests with the settings from the DEFAULT
section of tests.cfg
.
To run with a different tests.cfg
section:
py.test --pymssql-section=<secname>
example:
py.test --pymssql-section=AllTestsWillRun
to avoid slow tests:
py.test -m "not slow"
to select specific tests to run:
py.test tests/test_types.py
py.test tests/test_types.py tests/test_sprocs.py
py.test tests/test_types.py::TestTypes
py.test tests/test_types.py::TestTypes::test_image