pg8000-1.10.6/0000775000175000017500000000000012726514145013312 5ustar tlocketlocke00000000000000pg8000-1.10.6/MANIFEST.in0000664000175000017500000000014512720663214015044 0ustar tlocketlocke00000000000000include README.creole include versioneer.py include pg8000/_version.py include LICENSE include doc/* pg8000-1.10.6/setup.py0000664000175000017500000000437312720663214015027 0ustar tlocketlocke00000000000000#!/usr/bin/env python import versioneer from setuptools import setup long_description = """\ pg8000 ------ pg8000 is a Pure-Python interface to the PostgreSQL database engine. It is \ one of many PostgreSQL interfaces for the Python programming language. pg8000 \ is somewhat distinctive in that it is written entirely in Python and does not \ rely on any external libraries (such as a compiled python module, or \ PostgreSQL's libpq library). pg8000 supports the standard Python DB-API \ version 2.0. pg8000's name comes from the belief that it is probably about the 8000th \ PostgreSQL interface for Python.""" cmdclass = dict(versioneer.get_cmdclass()) version = versioneer.get_version() try: from sphinx.setup_command import BuildDoc cmdclass['build_sphinx'] = BuildDoc except ImportError: pass setup( name="pg8000", version=version, cmdclass=cmdclass, description="PostgreSQL interface library", long_description=long_description, author="Mathieu Fenniak", author_email="biziqe@mathieu.fenniak.net", url="https://github.com/mfenniak/pg8000", license="BSD", install_requires = [ "six>=1.10.0", ], classifiers=[ "Development Status :: 4 - Beta", "Intended Audience :: Developers", "License :: OSI Approved :: BSD License", "Programming Language :: Python", "Programming Language :: Python :: 2", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.3", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: Implementation", "Programming Language :: Python :: Implementation :: CPython", "Programming Language :: Python :: Implementation :: Jython", "Programming Language :: Python :: Implementation :: PyPy", "Operating System :: OS Independent", "Topic :: Database :: Front-Ends", "Topic :: Software Development :: Libraries :: Python Modules", ], keywords="postgresql dbapi", packages=("pg8000",), command_options={ 'build_sphinx': { 'version': ('setup.py', version), 'release': ('setup.py', version)}}, ) pg8000-1.10.6/pg8000.egg-info/0000775000175000017500000000000012726514145015722 5ustar tlocketlocke00000000000000pg8000-1.10.6/pg8000.egg-info/PKG-INFO0000664000175000017500000000331612726514135017021 0ustar tlocketlocke00000000000000Metadata-Version: 1.1 Name: pg8000 Version: 1.10.6 Summary: PostgreSQL interface library Home-page: https://github.com/mfenniak/pg8000 Author: Mathieu Fenniak Author-email: biziqe@mathieu.fenniak.net License: BSD Description: pg8000 ------ pg8000 is a Pure-Python interface to the PostgreSQL database engine. It is one of many PostgreSQL interfaces for the Python programming language. pg8000 is somewhat distinctive in that it is written entirely in Python and does not rely on any external libraries (such as a compiled python module, or PostgreSQL's libpq library). pg8000 supports the standard Python DB-API version 2.0. pg8000's name comes from the belief that it is probably about the 8000th PostgreSQL interface for Python. Keywords: postgresql dbapi Platform: UNKNOWN Classifier: Development Status :: 4 - Beta Classifier: Intended Audience :: Developers Classifier: License :: OSI Approved :: BSD License Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 2 Classifier: Programming Language :: Python :: 2.7 Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.3 Classifier: Programming Language :: Python :: 3.4 Classifier: Programming Language :: Python :: 3.5 Classifier: Programming Language :: Python :: Implementation Classifier: Programming Language :: Python :: Implementation :: CPython Classifier: Programming Language :: Python :: Implementation :: Jython Classifier: Programming Language :: Python :: Implementation :: PyPy Classifier: Operating System :: OS Independent Classifier: Topic :: Database :: Front-Ends Classifier: Topic :: Software Development :: Libraries :: Python Modules pg8000-1.10.6/pg8000.egg-info/top_level.txt0000664000175000017500000000000712726514135020450 0ustar tlocketlocke00000000000000pg8000 pg8000-1.10.6/pg8000.egg-info/dependency_links.txt0000664000175000017500000000000112726514135021767 0ustar tlocketlocke00000000000000 pg8000-1.10.6/pg8000.egg-info/requires.txt0000664000175000017500000000001412726514135020314 0ustar tlocketlocke00000000000000six>=1.10.0 pg8000-1.10.6/pg8000.egg-info/SOURCES.txt0000664000175000017500000000057012726514141017604 0ustar tlocketlocke00000000000000LICENSE MANIFEST.in README.creole setup.cfg setup.py versioneer.py doc/Makefile doc/conf.py doc/dbapi.rst doc/index.rst doc/quickstart.rst doc/release_notes.rst doc/types.rst pg8000/__init__.py pg8000/_version.py pg8000/core.py pg8000.egg-info/PKG-INFO pg8000.egg-info/SOURCES.txt pg8000.egg-info/dependency_links.txt pg8000.egg-info/requires.txt pg8000.egg-info/top_level.txtpg8000-1.10.6/PKG-INFO0000664000175000017500000000331612726514145014412 0ustar tlocketlocke00000000000000Metadata-Version: 1.1 Name: pg8000 Version: 1.10.6 Summary: PostgreSQL interface library Home-page: https://github.com/mfenniak/pg8000 Author: Mathieu Fenniak Author-email: biziqe@mathieu.fenniak.net License: BSD Description: pg8000 ------ pg8000 is a Pure-Python interface to the PostgreSQL database engine. It is one of many PostgreSQL interfaces for the Python programming language. pg8000 is somewhat distinctive in that it is written entirely in Python and does not rely on any external libraries (such as a compiled python module, or PostgreSQL's libpq library). pg8000 supports the standard Python DB-API version 2.0. pg8000's name comes from the belief that it is probably about the 8000th PostgreSQL interface for Python. Keywords: postgresql dbapi Platform: UNKNOWN Classifier: Development Status :: 4 - Beta Classifier: Intended Audience :: Developers Classifier: License :: OSI Approved :: BSD License Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 2 Classifier: Programming Language :: Python :: 2.7 Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.3 Classifier: Programming Language :: Python :: 3.4 Classifier: Programming Language :: Python :: 3.5 Classifier: Programming Language :: Python :: Implementation Classifier: Programming Language :: Python :: Implementation :: CPython Classifier: Programming Language :: Python :: Implementation :: Jython Classifier: Programming Language :: Python :: Implementation :: PyPy Classifier: Operating System :: OS Independent Classifier: Topic :: Database :: Front-Ends Classifier: Topic :: Software Development :: Libraries :: Python Modules pg8000-1.10.6/doc/0000775000175000017500000000000012726514145014057 5ustar tlocketlocke00000000000000pg8000-1.10.6/doc/types.rst0000664000175000017500000001504512720663214015756 0ustar tlocketlocke00000000000000Type Mapping ============ The following table shows the mapping between Python types and PostgreSQL types, and vice versa. If pg8000 doesn't recognize a type that it receives from PostgreSQL, it will return it as a ``str`` type. This is how pg8000 handles PostgreSQL ``enum`` and XML types. +--------------------------------+-----------------+---------------------------+ | Python Type | PostgreSQL Type | Notes | +================================+=================+===========================+ | :class:`bool` | bool | | +--------------------------------+-----------------+---------------------------+ | :class:`int` | int4 | | +--------------------------------+-----------------+---------------------------+ | :class:`long` | numeric | Python 2 only. | +--------------------------------+-----------------+---------------------------+ | :class:`str` | text (Python 3) | | | | bytea (Python 2)| | +--------------------------------+-----------------+---------------------------+ | :class:`unicode` | text | Python 2 only. | +--------------------------------+-----------------+---------------------------+ | :class:`float` | float8 | | +--------------------------------+-----------------+---------------------------+ | :class:`decimal.Decimal` | numeric | | +--------------------------------+-----------------+---------------------------+ | :class:`pg8000.Bytea` | bytea | Python 2 only. | +--------------------------------+-----------------+---------------------------+ | :class:`bytes` | bytea | Python 3 only. | +--------------------------------+-----------------+---------------------------+ | :class:`datetime.datetime` | timestamp | ``datetime.datetime.max`` | | (wo/ tzinfo) | without time | maps to ``infinity``, and | | | zone | ``datetime.datetime.min`` | | | | maps to ``-infinity``. | +--------------------------------+-----------------+---------------------------+ | :class:`datetime.datetime` | timestamp with | ``datetime.datetime.max`` | | (w/ tzinfo) | time zone | maps to ``infinity``, and | | | | ``datetime.datetime.min`` | | | | maps to ``-infinity``. | | | | The max and min datetimes | | | | have a UTC timezone. | +--------------------------------+-----------------+---------------------------+ | :class:`datetime.date` | date | ``datetime.date.max`` | | | | maps to ``infinity``, and | | | | ``datetime.date.min`` | | | | maps to ``-infinity``. | +--------------------------------+-----------------+---------------------------+ | :class:`datetime.time` | time without | | | | time zone | | +--------------------------------+-----------------+---------------------------+ | :class:`datetime.timedelta` | interval | datetime.timedelta is | | :class:`pg8000.Interval` | | used unless the interval | | | | has months, in which case | | | | pg8000.Interval is used | +--------------------------------+-----------------+---------------------------+ | None | NULL | | +--------------------------------+-----------------+---------------------------+ | :class:`uuid.UUID` | uuid | | +--------------------------------+-----------------+---------------------------+ | :class:`ipaddress.IPv4Address` | inet | Python 3.3 onwards | +--------------------------------+-----------------+---------------------------+ | :class:`ipaddress.IPv6Address` | inet | Python 3.3 onwards | +--------------------------------+-----------------+---------------------------+ | :class:`ipaddress.IPv4Network` | inet | Python 3.3 onwards | +--------------------------------+-----------------+---------------------------+ | :class:`ipaddress.IPv6Network` | inet | Python 3.3 onwards | +--------------------------------+-----------------+---------------------------+ | :class:`int` | xid | | +--------------------------------+-----------------+---------------------------+ | list of :class:`int` | INT4[] | | +--------------------------------+-----------------+---------------------------+ | list of :class:`float` | FLOAT8[] | | +--------------------------------+-----------------+---------------------------+ | list of :class:`bool` | BOOL[] | | +--------------------------------+-----------------+---------------------------+ | list of :class:`str` | TEXT[] | | +--------------------------------+-----------------+---------------------------+ | list of :class:`unicode` | TEXT[] | Python 2 only. | +--------------------------------+-----------------+---------------------------+ | list of :class:`int` | int2vector | Only from PostgreSQL to | | | | Python | +--------------------------------+-----------------+---------------------------+ | JSON | json, jsonb | JSON string as an SQL | | | | parameter. Results | | | | returned as de-serialized | | | | JSON. | +--------------------------------+-----------------+---------------------------+ pg8000-1.10.6/doc/dbapi.rst0000664000175000017500000000331712720663214015670 0ustar tlocketlocke00000000000000.. module:: pg8000 API Reference for pg8000. Properties ---------- .. autodata:: __version__ :annotation: .. autodata:: apilevel :annotation: .. autodata:: threadsafety :annotation: .. autodata:: paramstyle :annotation: .. autodata:: STRING :annotation: .. attribute:: BINARY .. autodata:: NUMBER :annotation: .. autodata:: DATETIME :annotation: .. autodata:: ROWID :annotation: Functions --------- .. autofunction:: connect .. autofunction:: Date .. autofunction:: Time .. autofunction:: Timestamp .. autofunction:: DateFromTicks .. autofunction:: TimeFromTicks .. autofunction:: TimestampFromTicks .. autofunction:: Binary Generic Exceptions ------------------ pg8000 uses the standard DBAPI 2.0 exception tree as "generic" exceptions. Generally, more specific exception types are raised; these specific exception types are derived from the generic exceptions. .. autoexception:: Warning .. autoexception:: Error .. autoexception:: InterfaceError .. autoexception:: DatabaseError .. autoexception:: DataError .. autoexception:: OperationalError .. autoexception:: IntegrityError .. autoexception:: InternalError .. autoexception:: ProgrammingError .. autoexception:: NotSupportedError Specific Exceptions ------------------- Exceptions that are subclassed from the standard DB-API 2.0 exceptions above. .. autoexception:: ArrayContentNotSupportedError .. autoexception:: ArrayContentNotHomogenousError .. autoexception:: ArrayContentEmptyError .. autoexception:: ArrayDimensionsNotConsistentError Classes ------- .. autoclass:: Connection() :members: .. autoclass:: Cursor() :members: Type Classes ------------ .. autoclass:: Bytea .. autoclass:: Interval pg8000-1.10.6/doc/quickstart.rst0000664000175000017500000000652612720663214017010 0ustar tlocketlocke00000000000000Quick Start =========== Key Points ---------- - Runs on Python versions 2.7+ and 3.3+ - Runs on CPython, Jython and PyPy - Although it's possible for threads to share cursors and connections, for performance reasons it's best to use one thread per connection. - Internally, all queries use prepared statements. pg8000 remembers that a prepared statement has been created, and uses it on subsequent queries. Installation ------------ To install pg8000 using `pip `_ type: ``pip install pg8000`` Interactive Example ------------------- Import pg8000, connect to the database, create a table, add some rows and then query the table: .. code-block:: python >>> import pg8000 >>> conn = pg8000.connect(user="postgres", password="C.P.Snow") >>> cursor = conn.cursor() >>> cursor.execute("CREATE TEMPORARY TABLE book (id SERIAL, title TEXT)") >>> cursor.execute( ... "INSERT INTO book (title) VALUES (%s), (%s) RETURNING id, title", ... ("Ender's Game", "Speaker for the Dead")) >>> results = cursor.fetchall() >>> for row in results: ... id, title = row ... print("id = %s, title = %s" % (id, title)) id = 1, title = Ender's Game id = 2, title = Speaker for the Dead >>> conn.commit() Another query, using some PostgreSQL functions: .. code-block:: python >>> cursor.execute("SELECT extract(millennium from now())") >>> cursor.fetchone() [3.0] A query that returns the PostgreSQL interval type: .. code-block:: python >>> import datetime >>> cursor.execute("SELECT timestamp '2013-12-01 16:06' - %s", ... (datetime.date(1980, 4, 27),)) >>> cursor.fetchone() [datetime.timedelta(12271, 57960)] pg8000 supports all the DB-API parameter styles. Here's an example of using the 'numeric' parameter style: .. code-block:: python >>> pg8000.paramstyle = "numeric" >>> cursor.execute("SELECT array_prepend(:1, :2)", ( 500, [1, 2, 3, 4], )) >>> cursor.fetchone() [[500, 1, 2, 3, 4]] >>> pg8000.paramstyle = "format" >>> conn.rollback() Following the DB-API specification, autocommit is off by default. It can be turned on by using the autocommit property of the connection. .. code-block:: python >>> conn.autocommit = True >>> cur = conn.cursor() >>> cur.execute("vacuum") >>> conn.autocommit = False >>> cursor.close() When communicating with the server, pg8000 uses the character set that the server asks it to use (the client encoding). By default the client encoding is the database's character set (chosen when the database is created), but the client encoding can be changed in a number of ways (eg. setting CLIENT_ENCODING in postgresql.conf). Another way of changing the client encoding is by using an SQL command. For example: .. code-block:: python >>> cur = conn.cursor() >>> cur.execute("SET CLIENT_ENCODING TO 'UTF8'") >>> cur.execute("SHOW CLIENT_ENCODING") >>> cur.fetchone() ['UTF8'] >>> cur.close() JSON is sent to the server serialized, and returned de-serialized. Here's an example: .. code-block:: python >>> import json >>> cur = conn.cursor() >>> val = ['Apollo 11 Cave', True, 26.003] >>> cur.execute("SELECT cast(%s as json)", (json.dumps(val),)) >>> cur.fetchone() [['Apollo 11 Cave', True, 26.003]] >>> cur.close() >>> conn.close() pg8000-1.10.6/doc/Makefile0000664000175000017500000001515612720663214015523 0ustar tlocketlocke00000000000000# Makefile for Sphinx documentation # # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = BUILDDIR = build # User-friendly check for sphinx-build ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) endif # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext help: @echo "Please use \`make ' where is one of" @echo " html to make standalone HTML files" @echo " dirhtml to make HTML files named index.html in directories" @echo " singlehtml to make a single large HTML file" @echo " pickle to make pickle files" @echo " json to make JSON files" @echo " htmlhelp to make HTML files and a HTML help project" @echo " qthelp to make HTML files and a qthelp project" @echo " devhelp to make HTML files and a Devhelp project" @echo " epub to make an epub" @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" @echo " latexpdf to make LaTeX files and run them through pdflatex" @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" @echo " text to make text files" @echo " man to make manual pages" @echo " texinfo to make Texinfo files" @echo " info to make Texinfo files and run them through makeinfo" @echo " gettext to make PO message catalogs" @echo " changes to make an overview of all changed/added/deprecated items" @echo " xml to make Docutils-native XML files" @echo " pseudoxml to make pseudoxml-XML files for display purposes" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" clean: rm -rf $(BUILDDIR)/* html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." singlehtml: $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml @echo @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." pickle: $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." json: $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." htmlhelp: $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp @echo @echo "Build finished; now you can run HTML Help Workshop with the" \ ".hhp project file in $(BUILDDIR)/htmlhelp." qthelp: $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ ".qhcp project file in $(BUILDDIR)/qthelp, like this:" @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/pg8000.qhcp" @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pg8000.qhc" devhelp: $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp @echo @echo "Build finished." @echo "To view the help file:" @echo "# mkdir -p $$HOME/.local/share/devhelp/pg8000" @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pg8000" @echo "# devhelp" epub: $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub @echo @echo "Build finished. The epub file is in $(BUILDDIR)/epub." latex: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." @echo "Run \`make' in that directory to run these through (pdf)latex" \ "(use \`make latexpdf' here to do that automatically)." latexpdf: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through pdflatex..." $(MAKE) -C $(BUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." latexpdfja: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through platex and dvipdfmx..." $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." text: $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text @echo @echo "Build finished. The text files are in $(BUILDDIR)/text." man: $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." texinfo: $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @echo @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." @echo "Run \`make' in that directory to run these through makeinfo" \ "(use \`make info' here to do that automatically)." info: $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @echo "Running Texinfo files through makeinfo..." make -C $(BUILDDIR)/texinfo info @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." gettext: $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale @echo @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." changes: $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." linkcheck: $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/output.txt." doctest: $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." xml: $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml @echo @echo "Build finished. The XML files are in $(BUILDDIR)/xml." pseudoxml: $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml @echo @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." pg8000-1.10.6/doc/index.rst0000664000175000017500000000234412720663214015717 0ustar tlocketlocke00000000000000########## pg8000 ########## pg8000 is a `DB-API 2.0 `_ compatible pure-Python interface to the `PostgreSQL `_ database engine. It is one of many PostgreSQL interfaces for the Python programming language. pg8000 is somewhat distinctive in that it is written entirely in Python and does not rely on any external libraries (such as a compiled python module, or PostgreSQL's libpq library). pg8000's name comes from the belief that it is probably about the 8000th PostgreSQL interface for Python. pg8000 is distributed under the terms of the BSD 3-clause license. All bug reports, feature requests and contributions are welcome at http://github.com/mfenniak/pg8000/. There's also a forum at https://groups.google.com/forum/#!forum/pg8000. If you're a user of pg8000 we'd love to hear who you are and what you or your organization is using pg8000 for. Just log an issue on GitHub or post a message to the forum. The idea is to put together a page of users. Contents -------- .. toctree:: :maxdepth: 2 quickstart dbapi types release_notes Indices and tables ------------------ * :ref:`genindex` * :ref:`search` pg8000-1.10.6/doc/release_notes.rst0000664000175000017500000005271212726513357017454 0ustar tlocketlocke00000000000000Release Notes ============= Version 1.10.6, 2016-06-10 -------------------------- - Fixed a problem where we weren't handling the password connection parameter correctly. Now it's handled in the same way as the 'user' and 'database' parameters, ie. if the password is bytes, then pass it straight through to the database, if it's a string then encode it with utf8. - It used to be that if the 'user' parameter to the connection function was 'None', then pg8000 would try and look at environment variables to find a username. Now we just go by the 'user' parameter only, and give an error if it's None. Version 1.10.5, 2016-03-04 -------------------------- - Include LICENCE text and sources for docs in the source distribution (the tarball). Version 1.10.4, 2016-02-27 -------------------------- - Fixed bug where if a str is sent as a query parameter, and then with the same cursor an int is sent instead of a string, for the same query, then it fails. - Under Python 2, a str type is now sent 'as is', ie. as a byte string rather than trying to decode and send according to the client encoding. Under Python 2 it's recommended to send text as unicode() objects. - Dropped and added support for Python versions. Now pg8000 supports Python 2.7+ and Python 3.3+. - Dropped and added support for PostgreSQL versions. Now pg8000 supports PostgreSQL 9.1+. - pg8000 uses the 'six' library for making the same code run on both Python 2 and Python 3. We used to include it as a file in the pg8000 source code. Now we have it as a separate dependency that's installed with 'pip install'. The reason for doing this is that package maintainers for OS distributions prefer unbundled libaries. Version 1.10.3, 2016-01-07 -------------------------- - Removed testing for PostgreSQL 9.0 as it's not longer supported by the PostgreSQL Global Development Group. - Fixed bug where pg8000 would fail with datetimes if PostgreSQL was compiled with the integer_datetimes option set to 'off'. The bug was in the timestamp_send_float function. Version 1.10.2, 2015-03-17 -------------------------- - If there's a socket exception thrown when communicating with the database, it is now wrapped in an OperationalError exception, to conform to the DB-API spec. - Previously, pg8000 didn't recognize the EmptyQueryResponse (that the server sends back if the SQL query is an empty string) now we raise a ProgrammingError exception. - Added socket timeout option for Python 3. - If the server returns an error, we used to initialize the ProgramerException with just the first three fields of the error. Now we initialize the ProgrammerException with all the fields. - Use relative imports inside package. - User and database names given as bytes. The user and database parameters of the connect() function are now passed directly as bytes to the server. If the type of the parameter is unicode, pg8000 converts it to bytes using the uft8 encoding. - Added support for JSON and JSONB Postgres types. We take the approach of taking serialized JSON (str) as an SQL parameter, but returning results as de-serialized JSON (Python objects). See the example in the Quickstart. - Added CircleCI continuous integration. - String support in arrays now allow letters like "u", braces and whitespace. Version 1.10.1, 2014-09-15 -------------------------- - Add support for the Wheel package format. - Remove option to set a connection timeout. For communicating with the server, pg8000 uses a file-like object using socket.makefile() but you can't use this if the underlying socket has a timeout. Version 1.10.0, 2014-08-30 -------------------------- - Remove the old ``pg8000.dbapi`` and ``pg8000.DBAPI`` namespaces. For example, now only ``pg8000.connect()`` will work, and ``pg8000.dbapi.connect()`` won't work any more. - Parse server version string with LooseVersion. This should solve the problems that people have been having when using versions of PostgreSQL such as ``9.4beta2``. - Message if portal suspended in autocommit. Give a proper error message if the portal is suspended while in autocommit mode. The error is that the portal is closed when the transaction is closed, and so in autocommit mode the portal will be immediately closed. The bottom line is, don't use autocommit mode if there's a chance of retrieving more rows than the cache holds (currently 100). Version 1.9.14, 2014-08-02 -------------------------- - Make ``executemany()`` set ``rowcount``. Previously, ``executemany()`` would always set ``rowcount`` to -1. Now we set it to a meaningful value if possible. If any of the statements have a -1 ``rowcount`` then then the ``rowcount`` for the ``executemany()`` is -1, otherwise the ``executemany()`` ``rowcount`` is the sum of the rowcounts of the individual statements. - Support for password authentication. pg8000 didn't support plain text authentication, now it does. Version 1.9.13, 2014-07-27 -------------------------- - Reverted to using the string ``connection is closed`` as the message of the exception that's thrown if a connection is closed. For a few versions we were using a slightly different one with capitalization and punctuation, but we've reverted to the original because it's easier for users of the library to consume. - Previously, ``tpc_recover()`` would start a transaction if one was not already in progress. Now it won't. Version 1.9.12, 2014-07-22 -------------------------- - Fixed bug in ``tpc_commit()`` where a single phase commit failed. Version 1.9.11, 2014-07-20 -------------------------- - Add support for two-phase commit DBAPI extension. Thanks to Mariano Reingart's TPC code on the Google Code version: https://code.google.com/p/pg8000/source/detail?r=c8609701b348b1812c418e2c7 on which the code for this commit is based. - Deprecate ``copy_from()`` and ``copy_to()`` The methods ``copy_from()`` and ``copy_to()`` of the ``Cursor`` object are deprecated because it's simpler and more flexible to use the ``execute()`` method with a ``fileobj`` parameter. - Fixed bug in reporting unsupported authentication codes. Thanks to https://github.com/hackgnar for reporting this and providing the fix. - Have a default for the ``user`` paramater of the ``connect()`` function. If the ``user`` parameter of the ``connect()`` function isn't provided, look first for the ``PGUSER`` then the ``USER`` environment variables. Thanks to Alex Gaynor https://github.com/alex for this suggestion. - Before PostgreSQL 8.2, ``COPY`` didn't give row count. Until PostgreSQL 8.2 (which includes Amazon Redshift which forked at 8.0) the ``COPY`` command didn't return a row count, but pg8000 thought it did. That's fixed now. Version 1.9.10, 2014-06-08 -------------------------- - Remember prepared statements. Now prepared statements are never closed, and pg8000 remembers which ones are on the server, and uses them when a query is repeated. This gives an increase in performance, because on subsequent queries the prepared statement doesn't need to be created each time. - For performance reasons, pg8000 never closed portals explicitly, it just let the server close them at the end of the transaction. However, this can cause memory problems for long running transactions, so now pg800 always closes a portal after it's exhausted. - Fixed bug where unicode arrays failed under Python 2. Thanks to https://github.com/jdkx for reporting this. - A FLUSH message is now sent after every message (except SYNC). This is in accordance with the protocol docs, and ensures the server sends back its responses straight away. Version 1.9.9, 2014-05-12 ------------------------- - The PostgreSQL interval type is now mapped to datetime.timedelta where possible. Previously the PostgreSQL interval type was always mapped to the pg8000.Interval type. However, to support the datetime.timedelta type we now use it whenever possible. Unfortunately it's not always possible because timedelta doesn't support months. If months are needed then the fall-back is the pg8000.Interval type. This approach means we handle timedelta in a similar way to other Python PostgreSQL drivers, and it makes pg8000 compatible with popular ORMs like SQLAlchemy. * Fixed bug in executemany() where a new prepared statement should be created for each variation in the oids of the parameter sets. Version 1.9.8, 2014-05-05 ------------------------- - We used to ask the server for a description of the statement, and then ask for a description of each subsequent portal. We now only ask for a description of the statement. This results in a significant performance improvement, especially for executemany() calls and when using the 'use_cache' option of the connect() function. - Fixed warning in Python 3.4 which was saying that a socket hadn't been closed. It seems that closing a socket file doesn't close the underlying socket. - Now should cope with PostgreSQL 8 versions before 8.4. This includes Amazon Redshift. - Added 'unicode' alias for 'utf-8', which is needed for Amazon Redshift. - Various other bug fixes. Version 1.9.7, 2014-03-26 ------------------------- - Caching of prepared statements. There's now a 'use_cache' boolean parameter for the connect() function, which causes all prepared statements to be cached by pg8000, keyed on the SQL query string. This should speed things up significantly in most cases. - Added support for the PostgreSQL inet type. It maps to the Python types IPv*Address and IPv*Network. - Added support for PostgreSQL +/- infinity date and timestamp values. Now the Python value datetime.datetime.max maps to the PostgreSQL value 'infinity' and datetime.datetime.min maps to '-infinity', and the same for datetime.date. - Added support for the PostgreSQL types int2vector and xid, which are mostly used internally by PostgreSQL. Version 1.9.6, 2014-02-26 ------------------------- - Fixed a bug where 'portal does not exist' errors were being generated. Some queries that should have been run in a transaction were run in autocommit mode and so any that suspended a portal had the portal immediately closed, because a portal can only exist within a transaction. This has been solved by determining the transaction status from the READY_FOR_QUERY message. Version 1.9.5, 2014-02-15 ------------------------- - Removed warn() calls for __next__() and __iter__(). Removing the warn() in __next__() improves the performance tests by ~20%. - Increased performance of timestamp by ~20%. Should also improve timestamptz. - Moved statement_number and portal_number from module to Connection. This should reduce lock contention for cases where there's a single module and lots of connections. - Make decimal_out/in and time_in use client_encoding. These functions used to assume ascii, and I can't think of a case where that wouldn't work. Nonetheless, that theoretical bug is now fixed. - Fixed a bug in cursor.executemany(), where a non-None parameter in a sequence of parameters, is None in a subsequent sequence of parameters. Version 1.9.4, 2014-01-18 ------------------------- - Fixed a bug where with Python 2, a parameter with the value Decimal('12.44'), (and probably other numbers) isn't sent correctly to PostgreSQL, and so the command fails. This has been fixed by sending decimal types as text rather than binary. I'd imagine it's slightly faster too. Version 1.9.3, 2014-01-16 ------------------------- - Fixed bug where there were missing trailing zeros after the decimal point in the NUMERIC type. For example, the NUMERIC value 1.0 was returned as 1 (with no zero after the decimal point). This is fixed this by making pg8000 use the text rather than binary representation for the numeric type. This actually doubles the speed of numeric queries. Version 1.9.2, 2013-12-17 ------------------------- - Fixed incompatibility with PostgreSQL 8.4. In 8.4, the CommandComplete message doesn't return a row count if the command is SELECT. We now look at the server version and don't look for a row count for a SELECT with version 8.4. Version 1.9.1, 2013-12-15 ------------------------- - Fixed bug where the Python 2 'unicode' type wasn't recognized in a query parameter. Version 1.9.0, 2013-12-01 ------------------------- - For Python 3, the :class:`bytes` type replaces the :class:`pg8000.Bytea` type. For backward compatibility the :class:`pg8000.Bytea` still works under Python 3, but its use is deprecated. - A single codebase for Python 2 and 3. - Everything (functions, properties, classes) is now available under the ``pg8000`` namespace. So for example: - pg8000.DBAPI.connect() -> pg8000.connect() - pg8000.DBAPI.apilevel -> pg8000.apilevel - pg8000.DBAPI.threadsafety -> pg8000.threadsafety - pg8000.DBAPI.paramstyle -> pg8000.paramstyle - pg8000.types.Bytea -> pg8000.Bytea - pg8000.types.Interval -> pg8000.Interval - pg8000.errors.Warning -> pg8000.Warning - pg8000.errors.Error -> pg8000.Error - pg8000.errors.InterfaceError -> pg8000.InterfaceError - pg8000.errors.DatabaseError -> pg8000.DatabaseError The old locations are deprecated, but still work for backward compatibility. - Lots of performance improvements. - Faster receiving of ``numeric`` types. - Query only parsed when PreparedStatement is created. - PreparedStatement re-used in executemany() - Use ``collections.deque`` rather than ``list`` for the row cache. We're adding to one end and removing from the other. This is O(n) for a list but O(1) for a deque. - Find the conversion function and do the format code check in the ROW_DESCRIPTION handler, rather than every time in the ROW_DATA handler. - Use the 'unpack_from' form of struct, when unpacking the data row, so we don't have to slice the data. - Return row as a list for better performance. At the moment result rows are turned into a tuple before being returned. Returning the rows directly as a list speeds up the performance tests about 5%. - Simplify the event loop. Now the main event loop just continues until a READY_FOR_QUERY message is received. This follows the suggestion in the Postgres protocol docs. There's not much of a difference in speed, but the code is a bit simpler, and it should make things more robust. - Re-arrange the code as a state machine to give > 30% speedup. - Using pre-compiled struct objects. Pre-compiled struct objects are a bit faster than using the struct functions directly. It also hopefully adds to the readability of the code. - Speeded up _send. Before calling the socket 'write' method, we were checking that the 'data' type implements the 'buffer' interface (bytes or bytearray), but the check isn't needed because 'write' raises an exception if data is of the wrong type. - Add facility for turning auto-commit on. This follows the suggestion of funkybob to fix the problem of not be able to execute a command such as 'create database' that must be executed outside a transaction. Now you can do conn.autocommit = True and then execute 'create database'. - Add support for the PostgreSQL ``uid`` type. Thanks to Rad Cirskis. - Add support for the PostgreSQL XML type. - Add support for the PostgreSQL ``enum`` user defined types. - Fix a socket leak, where a problem opening a connection could leave a socket open. - Fix empty array issue. https://github.com/mfenniak/pg8000/issues/10 - Fix scale on ``numeric`` types. https://github.com/mfenniak/pg8000/pull/13 - Fix numeric_send. Thanks to Christian Hofstaedtler. Version 1.08, 2010-06-08 ------------------------ - Removed usage of deprecated :mod:`md5` module, replaced with :mod:`hashlib`. Thanks to Gavin Sherry for the patch. - Start transactions on execute or executemany, rather than immediately at the end of previous transaction. Thanks to Ben Moran for the patch. - Add encoding lookups where needed, to address usage of SQL_ASCII encoding. Thanks to Benjamin Schweizer for the patch. - Remove record type cache SQL query on every new pg8000 connection. - Fix and test SSL connections. - Handle out-of-band messages during authentication. Version 1.07, 2009-01-06 ------------------------ - Added support for :meth:`~pg8000.dbapi.CursorWrapper.copy_to` and :meth:`~pg8000.dbapi.CursorWrapper.copy_from` methods on cursor objects, to allow the usage of the PostgreSQL COPY queries. Thanks to Bob Ippolito for the original patch. - Added the :attr:`~pg8000.dbapi.ConnectionWrapper.notifies` and :attr:`~pg8000.dbapi.ConnectionWrapper.notifies_lock` attributes to DBAPI connection objects to provide access to server-side event notifications. Thanks again to Bob Ippolito for the original patch. - Improved performance using buffered socket I/O. - Added valid range checks for :class:`~pg8000.types.Interval` attributes. - Added binary transmission of :class:`~decimal.Decimal` values. This permits full support for NUMERIC[] types, both send and receive. - New `Sphinx `_-based website and documentation. Version 1.06, 2008-12-09 ------------------------ - pg8000-py3: a branch of pg8000 fully supporting Python 3.0. - New Sphinx-based documentation. - Support for PostgreSQL array types -- INT2[], INT4[], INT8[], FLOAT[], DOUBLE[], BOOL[], and TEXT[]. New support permits both sending and receiving these values. - Limited support for receiving RECORD types. If a record type is received, it will be translated into a Python dict object. - Fixed potential threading bug where the socket lock could be lost during error handling. Version 1.05, 2008-09-03 ------------------------ - Proper support for timestamptz field type: - Reading a timestamptz field results in a datetime.datetime instance that has a valid tzinfo property. tzinfo is always UTC. - Sending a datetime.datetime instance with a tzinfo value will be sent as a timestamptz type, with the appropriate tz conversions done. - Map postgres < -- > python text encodings correctly. - Fix bug where underscores were not permitted in pyformat names. - Support "%s" in a pyformat strin. - Add cursor.connection DB-API extension. - Add cursor.next and cursor.__iter__ DB-API extensions. - DBAPI documentation improvements. - Don't attempt rollback in cursor.execute if a ConnectionClosedError occurs. - Add warning for accessing exceptions as attributes on the connection object, as per DB-API spec. - Fix up open connection when an unexpected connection occurs, rather than leaving the connection in an unusable state. - Use setuptools/egg package format. Version 1.04, 2008-05-12 ------------------------ - DBAPI 2.0 compatibility: - rowcount returns rows affected when appropriate (eg. UPDATE, DELETE) - Fix CursorWrapper.description to return a 7 element tuple, as per spec. - Fix CursorWrapper.rowcount when using executemany. - Fix CursorWrapper.fetchmany to return an empty sequence when no more results are available. - Add access to DBAPI exceptions through connection properties. - Raise exception on closing a closed connection. - Change DBAPI.STRING to varchar type. - rowcount returns -1 when appropriate. - DBAPI implementation now passes Stuart Bishop's Python DB API 2.0 Anal Compliance Unit Test. - Make interface.Cursor class use unnamed prepared statement that binds to parameter value types. This change increases the accuracy of PG's query plans by including parameter information, hence increasing performance in some scenarios. - Raise exception when reading from a cursor without a result set. - Fix bug where a parse error may have rendered a connection unusable. Version 1.03, 2008-05-09 ------------------------ - Separate pg8000.py into multiple python modules within the pg8000 package. There should be no need for a client to change how pg8000 is imported. - Fix bug in row_description property when query has not been completed. - Fix bug in fetchmany dbapi method that did not properly deal with the end of result sets. - Add close methods to DB connections. - Add callback event handlers for server notices, notifications, and runtime configuration changes. - Add boolean type output. - Add date, time, and timestamp types in/out. - Add recognition of "SQL_ASCII" client encoding, which maps to Python's "ascii" encoding. - Add types.Interval class to represent PostgreSQL's interval data type, and appropriate wire send/receive methods. - Remove unused type conversion methods. Version 1.02, 2007-03-13 ------------------------ - Add complete DB-API 2.0 interface. - Add basic SSL support via ssl connect bool. - Rewrite pg8000_test.py to use Python's unittest library. - Add bytea type support. - Add support for parameter output types: NULL value, timestamp value, python long value. - Add support for input parameter type oid. Version 1.01, 2007-03-09 ------------------------ - Add support for writing floats and decimal objs up to PG backend. - Add new error handling code and tests to make sure connection can recover from a database error. - Fixed bug where timestamp types were not always returned in the same binary format from the PG backend. Text format is now being used to send timestamps. - Fixed bug where large packets from the server were not being read fully, due to socket.read not always returning full read size requested. It was a lazy-coding bug. - Added locks to make most of the library thread-safe. - Added UNIX socket support. Version 1.00, 2007-03-08 ------------------------ - First public release. Although fully functional, this release is mostly lacking in production testing and in type support. pg8000-1.10.6/doc/conf.py0000664000175000017500000001312612720663214015355 0ustar tlocketlocke00000000000000# -*- coding: utf-8 -*- # # pg8000 documentation build configuration file, created by # sphinx-quickstart on Mon Sep 15 09:38:48 2008. # # This file is execfile()d with the current directory set to its containing dir. # # The contents of this file are pickled, so don't put values in the namespace # that aren't pickleable (module imports are okay, they're removed automatically). # # All configuration values have a default value; values that are commented out # serve to show the default value. import sys, os # If your extensions are in another directory, add it here. If the directory # is relative to the documentation root, use os.path.abspath to make it # absolute, like shown here. sys.path.append(os.path.abspath('../pg8000')) # General configuration # --------------------- # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc'] # Add any paths that contain templates here, relative to this directory. templates_path = ['.templates'] # The suffix of source filenames. source_suffix = '.rst' # The master toctree document. master_doc = 'index' # General substitutions. project = 'pg8000' copyright = '2008, Mathieu Fenniak' # 'version' and 'release' are set in setup.py # # The default replacements for |version| and |release|, also used in various # other places throughout the built documents. # # The short X.Y version. #version = '' # The full version, including alpha/beta/rc tags. #release = '' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: #today = '' # Else, today_fmt is used as the format for a strftime call. today_fmt = '%B %d, %Y' # List of documents that shouldn't be included in the build. #unused_docs = [] # List of directories, relative to source directories, that shouldn't be searched # for source files. #exclude_dirs = [] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. #add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). #add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. #show_authors = False # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # Options for HTML output # ----------------------- # The style sheet to use for HTML and HTML Help pages. A file of that name # must exist either in Sphinx' static/ path, or in one of the custom paths # given in html_static_path. html_style = 'default.css' # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". #html_title = None # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None # The name of an image file (within the static path) to place at the top of # the sidebar. #html_logo = None # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. #html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['.static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. html_last_updated_fmt = '%b %d, %Y' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. #html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. #html_additional_pages = {} # If false, no module index is generated. #html_use_modindex = True # If false, no index is generated. #html_use_index = True # If true, the index is split into individual pages for each letter. #html_split_index = False # If true, the reST sources are included in the HTML build as _sources/. #html_copy_source = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. #html_use_opensearch = '' # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). #html_file_suffix = '' # Output file base name for HTML help builder. htmlhelp_basename = 'pg8000doc' # Options for LaTeX output # ------------------------ # The paper size ('letter' or 'a4'). #latex_paper_size = 'letter' # The font size ('10pt', '11pt' or '12pt'). #latex_font_size = '10pt' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, document class [howto/manual]). latex_documents = [ ('index', 'pg8000.tex', 'pg8000 Documentation', 'Mathieu Fenniak', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of # the title page. #latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. #latex_use_parts = False # Additional stuff for the LaTeX preamble. #latex_preamble = '' # Documents to append as an appendix to all manuals. #latex_appendices = [] # If false, no module index is generated. #latex_use_modindex = True pg8000-1.10.6/pg8000/0000775000175000017500000000000012726514145014230 5ustar tlocketlocke00000000000000pg8000-1.10.6/pg8000/_version.py0000664000175000017500000000073012726514145016426 0ustar tlocketlocke00000000000000 # This file was generated by 'versioneer.py' (0.15) from # revision-control system data, or from the parent directory name of an # unpacked source archive. Distribution tarballs contain a pre-generated copy # of this file. import json import sys version_json = ''' { "dirty": false, "error": null, "full-revisionid": "4098abf6be90683ab10b7b080983ed6f08476485", "version": "1.10.6" } ''' # END VERSION_JSON def get_versions(): return json.loads(version_json) pg8000-1.10.6/pg8000/core.py0000664000175000017500000025665112726512573015554 0ustar tlocketlocke00000000000000import datetime from datetime import timedelta from warnings import warn import socket import threading from struct import pack from hashlib import md5 from decimal import Decimal from collections import deque, defaultdict from itertools import count, islice from six.moves import map from six import b, PY2, integer_types, next, text_type, u, binary_type from uuid import UUID from copy import deepcopy from calendar import timegm from distutils.version import LooseVersion from struct import Struct import time import pg8000 # Copyright (c) 2007-2009, Mathieu Fenniak # All rights reserved. # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright notice, # this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above copyright notice, # this list of conditions and the following disclaimer in the documentation # and/or other materials provided with the distribution. # * The name of the author may not be used to endorse or promote products # derived from this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE # ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE # LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR # CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF # SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE # POSSIBILITY OF SUCH DAMAGE. __author__ = "Mathieu Fenniak" try: from json import loads except ImportError: pass # Can only use JSON with Python 2.6 and above ZERO = timedelta(0) class UTC(datetime.tzinfo): def utcoffset(self, dt): return ZERO def tzname(self, dt): return "UTC" def dst(self, dt): return ZERO utc = UTC() class Interval(object): """An Interval represents a measurement of time. In PostgreSQL, an interval is defined in the measure of months, days, and microseconds; as such, the pg8000 interval type represents the same information. Note that values of the :attr:`microseconds`, :attr:`days` and :attr:`months` properties are independently measured and cannot be converted to each other. A month may be 28, 29, 30, or 31 days, and a day may occasionally be lengthened slightly by a leap second. .. attribute:: microseconds Measure of microseconds in the interval. The microseconds value is constrained to fit into a signed 64-bit integer. Any attempt to set a value too large or too small will result in an OverflowError being raised. .. attribute:: days Measure of days in the interval. The days value is constrained to fit into a signed 32-bit integer. Any attempt to set a value too large or too small will result in an OverflowError being raised. .. attribute:: months Measure of months in the interval. The months value is constrained to fit into a signed 32-bit integer. Any attempt to set a value too large or too small will result in an OverflowError being raised. """ def __init__(self, microseconds=0, days=0, months=0): self.microseconds = microseconds self.days = days self.months = months def _setMicroseconds(self, value): if not isinstance(value, integer_types): raise TypeError("microseconds must be an integer type") elif not (min_int8 < value < max_int8): raise OverflowError( "microseconds must be representable as a 64-bit integer") else: self._microseconds = value def _setDays(self, value): if not isinstance(value, integer_types): raise TypeError("days must be an integer type") elif not (min_int4 < value < max_int4): raise OverflowError( "days must be representable as a 32-bit integer") else: self._days = value def _setMonths(self, value): if not isinstance(value, integer_types): raise TypeError("months must be an integer type") elif not (min_int4 < value < max_int4): raise OverflowError( "months must be representable as a 32-bit integer") else: self._months = value microseconds = property(lambda self: self._microseconds, _setMicroseconds) days = property(lambda self: self._days, _setDays) months = property(lambda self: self._months, _setMonths) def __repr__(self): return "" % ( self.months, self.days, self.microseconds) def __eq__(self, other): return other is not None and isinstance(other, Interval) and \ self.months == other.months and self.days == other.days and \ self.microseconds == other.microseconds def __neq__(self, other): return not self.__eq__(other) def pack_funcs(fmt): struc = Struct('!' + fmt) return struc.pack, struc.unpack_from i_pack, i_unpack = pack_funcs('i') h_pack, h_unpack = pack_funcs('h') q_pack, q_unpack = pack_funcs('q') d_pack, d_unpack = pack_funcs('d') f_pack, f_unpack = pack_funcs('f') iii_pack, iii_unpack = pack_funcs('iii') ii_pack, ii_unpack = pack_funcs('ii') qii_pack, qii_unpack = pack_funcs('qii') dii_pack, dii_unpack = pack_funcs('dii') ihihih_pack, ihihih_unpack = pack_funcs('ihihih') ci_pack, ci_unpack = pack_funcs('ci') bh_pack, bh_unpack = pack_funcs('bh') cccc_pack, cccc_unpack = pack_funcs('cccc') Struct('!i') min_int2, max_int2 = -2 ** 15, 2 ** 15 min_int4, max_int4 = -2 ** 31, 2 ** 31 min_int8, max_int8 = -2 ** 63, 2 ** 63 class Warning(Exception): """Generic exception raised for important database warnings like data truncations. This exception is not currently used by pg8000. This exception is part of the `DBAPI 2.0 specification `_. """ pass class Error(Exception): """Generic exception that is the base exception of all other error exceptions. This exception is part of the `DBAPI 2.0 specification `_. """ pass class InterfaceError(Error): """Generic exception raised for errors that are related to the database interface rather than the database itself. For example, if the interface attempts to use an SSL connection but the server refuses, an InterfaceError will be raised. This exception is part of the `DBAPI 2.0 specification `_. """ pass class DatabaseError(Error): """Generic exception raised for errors that are related to the database. This exception is currently never raised by pg8000. This exception is part of the `DBAPI 2.0 specification `_. """ pass class DataError(DatabaseError): """Generic exception raised for errors that are due to problems with the processed data. This exception is not currently raised by pg8000. This exception is part of the `DBAPI 2.0 specification `_. """ pass class OperationalError(DatabaseError): """ Generic exception raised for errors that are related to the database's operation and not necessarily under the control of the programmer. This exception is currently never raised by pg8000. This exception is part of the `DBAPI 2.0 specification `_. """ pass class IntegrityError(DatabaseError): """ Generic exception raised when the relational integrity of the database is affected. This exception is not currently raised by pg8000. This exception is part of the `DBAPI 2.0 specification `_. """ pass class InternalError(DatabaseError): """Generic exception raised when the database encounters an internal error. This is currently only raised when unexpected state occurs in the pg8000 interface itself, and is typically the result of a interface bug. This exception is part of the `DBAPI 2.0 specification `_. """ pass class ProgrammingError(DatabaseError): """Generic exception raised for programming errors. For example, this exception is raised if more parameter fields are in a query string than there are available parameters. This exception is part of the `DBAPI 2.0 specification `_. """ pass class NotSupportedError(DatabaseError): """Generic exception raised in case a method or database API was used which is not supported by the database. This exception is part of the `DBAPI 2.0 specification `_. """ pass class ArrayContentNotSupportedError(NotSupportedError): """ Raised when attempting to transmit an array where the base type is not supported for binary data transfer by the interface. """ pass class ArrayContentNotHomogenousError(ProgrammingError): """ Raised when attempting to transmit an array that doesn't contain only a single type of object. """ pass class ArrayContentEmptyError(ProgrammingError): """Raised when attempting to transmit an empty array. The type oid of an empty array cannot be determined, and so sending them is not permitted. """ pass class ArrayDimensionsNotConsistentError(ProgrammingError): """ Raised when attempting to transmit an array that has inconsistent multi-dimension sizes. """ pass class Bytea(binary_type): """Bytea is a str-derived class that is mapped to a PostgreSQL byte array. This class is only used in Python 2, the built-in ``bytes`` type is used in Python 3. """ pass def Date(year, month, day): """Constuct an object holding a date value. This function is part of the `DBAPI 2.0 specification `_. :rtype: :class:`datetime.date` """ return datetime.date(year, month, day) def Time(hour, minute, second): """Construct an object holding a time value. This function is part of the `DBAPI 2.0 specification `_. :rtype: :class:`datetime.time` """ return datetime.time(hour, minute, second) def Timestamp(year, month, day, hour, minute, second): """Construct an object holding a timestamp value. This function is part of the `DBAPI 2.0 specification `_. :rtype: :class:`datetime.datetime` """ return datetime.datetime(year, month, day, hour, minute, second) def DateFromTicks(ticks): """Construct an object holding a date value from the given ticks value (number of seconds since the epoch). This function is part of the `DBAPI 2.0 specification `_. :rtype: :class:`datetime.date` """ return Date(*time.localtime(ticks)[:3]) def TimeFromTicks(ticks): """Construct an objet holding a time value from the given ticks value (number of seconds since the epoch). This function is part of the `DBAPI 2.0 specification `_. :rtype: :class:`datetime.time` """ return Time(*time.localtime(ticks)[3:6]) def TimestampFromTicks(ticks): """Construct an object holding a timestamp value from the given ticks value (number of seconds since the epoch). This function is part of the `DBAPI 2.0 specification `_. :rtype: :class:`datetime.datetime` """ return Timestamp(*time.localtime(ticks)[:6]) def Binary(value): """Construct an object holding binary data. This function is part of the `DBAPI 2.0 specification `_. :rtype: :class:`pg8000.types.Bytea` for Python 2, otherwise :class:`bytes` """ if PY2: return Bytea(value) else: return value if PY2: BINARY = Bytea else: BINARY = bytes FC_TEXT = 0 FC_BINARY = 1 BINARY_SPACE = b(" ") DDL_COMMANDS = b("ALTER"), b("CREATE") def convert_paramstyle(style, query): # I don't see any way to avoid scanning the query string char by char, # so we might as well take that careful approach and create a # state-based scanner. We'll use int variables for the state. # 0 -- outside quoted string # 1 -- inside single-quote string '...' # 2 -- inside quoted identifier "..." # 3 -- inside escaped single-quote string, E'...' # 4 -- inside parameter name eg. :name OUTSIDE = 0 INSIDE_SQ = 1 INSIDE_QI = 2 INSIDE_ES = 3 INSIDE_PN = 4 in_quote_escape = False in_param_escape = False placeholders = [] output_query = [] param_idx = map(lambda x: "$" + str(x), count(1)) state = OUTSIDE prev_c = None for i, c in enumerate(query): if i + 1 < len(query): next_c = query[i + 1] else: next_c = None if state == OUTSIDE: if c == "'": output_query.append(c) if prev_c == 'E': state = INSIDE_ES else: state = INSIDE_SQ elif c == '"': output_query.append(c) state = INSIDE_QI elif style == "qmark" and c == "?": output_query.append(next(param_idx)) elif style == "numeric" and c == ":": output_query.append("$") elif style == "named" and c == ":": state = INSIDE_PN placeholders.append('') elif style == "pyformat" and c == '%' and next_c == "(": state = INSIDE_PN placeholders.append('') elif style in ("format", "pyformat") and c == "%": style = "format" if in_param_escape: in_param_escape = False output_query.append(c) else: if next_c == "%": in_param_escape = True elif next_c == "s": state = INSIDE_PN output_query.append(next(param_idx)) else: raise InterfaceError( "Only %s and %% are supported in the query.") else: output_query.append(c) elif state == INSIDE_SQ: if c == "'": output_query.append(c) if in_quote_escape: in_quote_escape = False else: if next_c == "'": in_quote_escape = True else: state = OUTSIDE elif style in ("pyformat", "format") and c == "%": # hm... we're only going to support an escaped percent sign if in_param_escape: in_param_escape = False output_query.append(c) else: if next_c == "%": in_param_escape = True else: raise InterfaceError( "'%" + next_c + "' not supported in a quoted " "string within the query string") else: output_query.append(c) elif state == INSIDE_QI: if c == '"': state = OUTSIDE output_query.append(c) elif style in ("pyformat", "format") and c == "%": # hm... we're only going to support an escaped percent sign if in_param_escape: in_param_escape = False output_query.append(c) else: if next_c == "%": in_param_escape = True else: raise InterfaceError( "'%" + next_c + "' not supported in a quoted " "string within the query string") else: output_query.append(c) elif state == INSIDE_ES: if c == "'" and prev_c != "\\": # check for escaped single-quote output_query.append(c) state = OUTSIDE elif style in ("pyformat", "format") and c == "%": # hm... we're only going to support an escaped percent sign if in_param_escape: in_param_escape = False output_query.append(c) else: if next_c == "%": in_param_escape = True else: raise InterfaceError( "'%" + next_c + "' not supported in a quoted " "string within the query string.") else: output_query.append(c) elif state == INSIDE_PN: if style == 'named': placeholders[-1] += c if next_c is None or (not next_c.isalnum() and next_c != '_'): state = OUTSIDE try: pidx = placeholders.index(placeholders[-1], 0, -1) output_query.append("$" + str(pidx + 1)) del placeholders[-1] except ValueError: output_query.append("$" + str(len(placeholders))) elif style == 'pyformat': if prev_c == ')' and c == "s": state = OUTSIDE try: pidx = placeholders.index(placeholders[-1], 0, -1) output_query.append("$" + str(pidx + 1)) del placeholders[-1] except ValueError: output_query.append("$" + str(len(placeholders))) elif c in "()": pass else: placeholders[-1] += c elif style == 'format': state = OUTSIDE prev_c = c if style in ('numeric', 'qmark', 'format'): def make_args(vals): return vals else: def make_args(vals): return tuple(vals[p] for p in placeholders) return ''.join(output_query), make_args EPOCH = datetime.datetime(2000, 1, 1) EPOCH_TZ = EPOCH.replace(tzinfo=utc) EPOCH_SECONDS = timegm(EPOCH.timetuple()) utcfromtimestamp = datetime.datetime.utcfromtimestamp INFINITY_MICROSECONDS = 2 ** 63 - 1 MINUS_INFINITY_MICROSECONDS = -1 * INFINITY_MICROSECONDS - 1 # data is 64-bit integer representing microseconds since 2000-01-01 def timestamp_recv_integer(data, offset, length): micros = q_unpack(data, offset)[0] try: return EPOCH + timedelta(microseconds=micros) except OverflowError as e: if micros == INFINITY_MICROSECONDS: return datetime.datetime.max elif micros == MINUS_INFINITY_MICROSECONDS: return datetime.datetime.min else: raise e # data is double-precision float representing seconds since 2000-01-01 def timestamp_recv_float(data, offset, length): return utcfromtimestamp(EPOCH_SECONDS + d_unpack(data, offset)[0]) # data is 64-bit integer representing microseconds since 2000-01-01 def timestamp_send_integer(v): if v == datetime.datetime.max: micros = INFINITY_MICROSECONDS elif v == datetime.datetime.min: micros = MINUS_INFINITY_MICROSECONDS else: micros = int( (timegm(v.timetuple()) - EPOCH_SECONDS) * 1e6) + v.microsecond return q_pack(micros) # data is double-precision float representing seconds since 2000-01-01 def timestamp_send_float(v): return d_pack(timegm(v.timetuple()) + v.microsecond / 1e6 - EPOCH_SECONDS) def timestamptz_send_integer(v): # timestamps should be sent as UTC. If they have zone info, # convert them. return timestamp_send_integer(v.astimezone(utc).replace(tzinfo=None)) def timestamptz_send_float(v): # timestamps should be sent as UTC. If they have zone info, # convert them. return timestamp_send_float(v.astimezone(utc).replace(tzinfo=None)) DATETIME_MAX_TZ = datetime.datetime.max.replace(tzinfo=utc) DATETIME_MIN_TZ = datetime.datetime.min.replace(tzinfo=utc) # return a timezone-aware datetime instance if we're reading from a # "timestamp with timezone" type. The timezone returned will always be # UTC, but providing that additional information can permit conversion # to local. def timestamptz_recv_integer(data, offset, length): micros = q_unpack(data, offset)[0] try: return EPOCH_TZ + timedelta(microseconds=micros) except OverflowError as e: if micros == INFINITY_MICROSECONDS: return DATETIME_MAX_TZ elif micros == MINUS_INFINITY_MICROSECONDS: return DATETIME_MIN_TZ else: raise e def timestamptz_recv_float(data, offset, length): return timestamp_recv_float(data, offset, length).replace(tzinfo=utc) def interval_send_integer(v): microseconds = v.microseconds try: microseconds += int(v.seconds * 1e6) except AttributeError: pass try: months = v.months except AttributeError: months = 0 return qii_pack(microseconds, v.days, months) def interval_send_float(v): seconds = v.microseconds / 1000.0 / 1000.0 try: seconds += v.seconds except AttributeError: pass try: months = v.months except AttributeError: months = 0 return dii_pack(seconds, v.days, months) def interval_recv_integer(data, offset, length): microseconds, days, months = qii_unpack(data, offset) if months == 0: seconds, micros = divmod(microseconds, 1e6) return datetime.timedelta(days, seconds, micros) else: return Interval(microseconds, days, months) def interval_recv_float(data, offset, length): seconds, days, months = dii_unpack(data, offset) if months == 0: secs, microseconds = divmod(seconds, 1e6) return datetime.timedelta(days, secs, microseconds) else: return Interval(int(seconds * 1000 * 1000), days, months) def int8_recv(data, offset, length): return q_unpack(data, offset)[0] def int2_recv(data, offset, length): return h_unpack(data, offset)[0] def int4_recv(data, offset, length): return i_unpack(data, offset)[0] def float4_recv(data, offset, length): return f_unpack(data, offset)[0] def float8_recv(data, offset, length): return d_unpack(data, offset)[0] def bytea_send(v): return v # bytea if PY2: def bytea_recv(data, offset, length): return Bytea(data[offset:offset + length]) else: def bytea_recv(data, offset, length): return data[offset:offset + length] def uuid_send(v): return v.bytes def uuid_recv(data, offset, length): return UUID(bytes=data[offset:offset+length]) TRUE = b("\x01") FALSE = b("\x00") def bool_send(v): return TRUE if v else FALSE NULL = i_pack(-1) NULL_BYTE = b('\x00') def null_send(v): return NULL def int_in(data, offset, length): return int(data[offset: offset + length]) class Cursor(): """A cursor object is returned by the :meth:`~Connection.cursor` method of a connection. It has the following attributes and methods: .. attribute:: arraysize This read/write attribute specifies the number of rows to fetch at a time with :meth:`fetchmany`. It defaults to 1. .. attribute:: connection This read-only attribute contains a reference to the connection object (an instance of :class:`Connection`) on which the cursor was created. This attribute is part of a DBAPI 2.0 extension. Accessing this attribute will generate the following warning: ``DB-API extension cursor.connection used``. .. attribute:: rowcount This read-only attribute contains the number of rows that the last ``execute()`` or ``executemany()`` method produced (for query statements like ``SELECT``) or affected (for modification statements like ``UPDATE``). The value is -1 if: - No ``execute()`` or ``executemany()`` method has been performed yet on the cursor. - There was no rowcount associated with the last ``execute()``. - At least one of the statements executed as part of an ``executemany()`` had no row count associated with it. - Using a ``SELECT`` query statement on PostgreSQL server older than version 9. - Using a ``COPY`` query statement on PostgreSQL server version 8.1 or older. This attribute is part of the `DBAPI 2.0 specification `_. .. attribute:: description This read-only attribute is a sequence of 7-item sequences. Each value contains information describing one result column. The 7 items returned for each column are (name, type_code, display_size, internal_size, precision, scale, null_ok). Only the first two values are provided by the current implementation. This attribute is part of the `DBAPI 2.0 specification `_. """ def __init__(self, connection): self._c = connection self.arraysize = 1 self.ps = None self._row_count = -1 self._cached_rows = deque() self.portal_name = None self.portal_suspended = False @property def connection(self): warn("DB-API extension cursor.connection used", stacklevel=3) return self._c @property def rowcount(self): return self._row_count description = property(lambda self: self._getDescription()) def _getDescription(self): if self.ps is None: return None row_desc = self.ps['row_desc'] if len(row_desc) == 0: return None columns = [] for col in row_desc: columns.append( (col["name"], col["type_oid"], None, None, None, None, None)) return columns ## # Executes a database operation. Parameters may be provided as a sequence # or mapping and will be bound to variables in the operation. #

# Stability: Part of the DBAPI 2.0 specification. def execute(self, operation, args=None, stream=None): """Executes a database operation. Parameters may be provided as a sequence, or as a mapping, depending upon the value of :data:`pg8000.paramstyle`. This method is part of the `DBAPI 2.0 specification `_. :param operation: The SQL statement to execute. :param args: If :data:`paramstyle` is ``qmark``, ``numeric``, or ``format``, this argument should be an array of parameters to bind into the statement. If :data:`paramstyle` is ``named``, the argument should be a dict mapping of parameters. If the :data:`paramstyle` is ``pyformat``, the argument value may be either an array or a mapping. :param stream: This is a pg8000 extension for use with the PostgreSQL `COPY `_ command. For a COPY FROM the parameter must be a readable file-like object, and for COPY TO it must be writable. .. versionadded:: 1.9.11 """ try: with self._c._lock: self.stream = stream if not self._c.in_transaction and not self._c.autocommit: self._c.execute(self, "begin transaction", None) self._c.execute(self, operation, args) except AttributeError as e: if self._c is None: raise InterfaceError("Cursor closed") elif self._c._sock is None: raise InterfaceError("connection is closed") else: raise e def executemany(self, operation, param_sets): """Prepare a database operation, and then execute it against all parameter sequences or mappings provided. This method is part of the `DBAPI 2.0 specification `_. :param operation: The SQL statement to execute :param parameter_sets: A sequence of parameters to execute the statement with. The values in the sequence should be sequences or mappings of parameters, the same as the args argument of the :meth:`execute` method. """ rowcounts = [] for parameters in param_sets: self.execute(operation, parameters) rowcounts.append(self._row_count) self._row_count = -1 if -1 in rowcounts else sum(rowcounts) def fetchone(self): """Fetch the next row of a query result set. This method is part of the `DBAPI 2.0 specification `_. :returns: A row as a sequence of field values, or ``None`` if no more rows are available. """ try: return next(self) except StopIteration: return None except TypeError: raise ProgrammingError("attempting to use unexecuted cursor") except AttributeError: raise ProgrammingError("attempting to use unexecuted cursor") def fetchmany(self, num=None): """Fetches the next set of rows of a query result. This method is part of the `DBAPI 2.0 specification `_. :param size: The number of rows to fetch when called. If not provided, the :attr:`arraysize` attribute value is used instead. :returns: A sequence, each entry of which is a sequence of field values making up a row. If no more rows are available, an empty sequence will be returned. """ try: return tuple( islice(self, self.arraysize if num is None else num)) except TypeError: raise ProgrammingError("attempting to use unexecuted cursor") def fetchall(self): """Fetches all remaining rows of a query result. This method is part of the `DBAPI 2.0 specification `_. :returns: A sequence, each entry of which is a sequence of field values making up a row. """ try: return tuple(self) except TypeError: raise ProgrammingError("attempting to use unexecuted cursor") def close(self): """Closes the cursor. This method is part of the `DBAPI 2.0 specification `_. """ self._c = None def __iter__(self): """A cursor object is iterable to retrieve the rows from a query. This is a DBAPI 2.0 extension. """ return self def setinputsizes(self, sizes): """This method is part of the `DBAPI 2.0 specification `_, however, it is not implemented by pg8000. """ pass def setoutputsize(self, size, column=None): """This method is part of the `DBAPI 2.0 specification `_, however, it is not implemented by pg8000. """ pass def __next__(self): with self._c._lock: try: return self._cached_rows.popleft() except IndexError: if self.portal_suspended: self._c.send_EXECUTE(self) self._c._write(SYNC_MSG) self._c._flush() self._c.handle_messages(self) if not self.portal_suspended: self._c.close_portal(self) try: return self._cached_rows.popleft() except IndexError: if self.ps is None: raise ProgrammingError("A query hasn't been issued.") elif len(self.ps['row_desc']) == 0: raise ProgrammingError("no result set") else: raise StopIteration() if PY2: Cursor.next = Cursor.__next__ # Message codes NOTICE_RESPONSE = b("N") AUTHENTICATION_REQUEST = b("R") PARAMETER_STATUS = b("S") BACKEND_KEY_DATA = b("K") READY_FOR_QUERY = b("Z") ROW_DESCRIPTION = b("T") ERROR_RESPONSE = b("E") DATA_ROW = b("D") COMMAND_COMPLETE = b("C") PARSE_COMPLETE = b("1") BIND_COMPLETE = b("2") CLOSE_COMPLETE = b("3") PORTAL_SUSPENDED = b("s") NO_DATA = b("n") PARAMETER_DESCRIPTION = b("t") NOTIFICATION_RESPONSE = b("A") COPY_DONE = b("c") COPY_DATA = b("d") COPY_IN_RESPONSE = b("G") COPY_OUT_RESPONSE = b("H") EMPTY_QUERY_RESPONSE = b("I") BIND = b("B") PARSE = b("P") EXECUTE = b("E") FLUSH = b('H') SYNC = b('S') PASSWORD = b('p') DESCRIBE = b('D') TERMINATE = b('X') CLOSE = b('C') FLUSH_MSG = FLUSH + i_pack(4) SYNC_MSG = SYNC + i_pack(4) TERMINATE_MSG = TERMINATE + i_pack(4) COPY_DONE_MSG = COPY_DONE + i_pack(4) # DESCRIBE constants STATEMENT = b('S') PORTAL = b('P') # ErrorResponse codes RESPONSE_SEVERITY = b("S") # always present RESPONSE_CODE = b("C") # always present RESPONSE_MSG = b("M") # always present RESPONSE_DETAIL = b("D") RESPONSE_HINT = b("H") RESPONSE_POSITION = b("P") RESPONSE__POSITION = b("p") RESPONSE__QUERY = b("q") RESPONSE_WHERE = b("W") RESPONSE_FILE = b("F") RESPONSE_LINE = b("L") RESPONSE_ROUTINE = b("R") IDLE = b("I") IDLE_IN_TRANSACTION = b("T") IDLE_IN_FAILED_TRANSACTION = b("E") arr_trans = dict(zip(map(ord, u("[] 'u")), list(u('{}')) + [None] * 3)) class MulticastDelegate(object): def __init__(self): self.delegates = [] def __iadd__(self, delegate): self.add(delegate) return self def add(self, delegate): self.delegates.append(delegate) def __isub__(self, delegate): self.delegates.remove(delegate) return self def __call__(self, *args, **kwargs): for d in self.delegates: d(*args, **kwargs) class Connection(object): """A connection object is returned by the :func:`pg8000.connect` function. It represents a single physical connection to a PostgreSQL database. .. attribute:: Connection.notifies A list of server-side notifications received by this database connection (via the LISTEN/NOTIFY PostgreSQL commands). Each list element is a two-element tuple containing the PostgreSQL backend PID that issued the notify, and the notification name. PostgreSQL will only send notifications to a client between transactions. The contents of this property are generally only populated after a commit or rollback of the current transaction. This list can be modified by a client application to clean out notifications as they are handled. However, inspecting or modifying this collection should only be done while holding the :attr:`notifies_lock` lock in order to guarantee thread-safety. This attribute is not part of the DBAPI standard; it is a pg8000 extension. .. versionadded:: 1.07 .. attribute:: Connection.notifies_lock A :class:`threading.Lock` object that should be held to read or modify the contents of the :attr:`notifies` list. This attribute is not part of the DBAPI standard; it is a pg8000 extension. .. versionadded:: 1.07 .. attribute:: Connection.autocommit Following the DB-API specification, autocommit is off by default. It can be turned on by setting this boolean pg8000-specific autocommit property to True. .. versionadded:: 1.9 .. exception:: Connection.Error Connection.Warning Connection.InterfaceError Connection.DatabaseError Connection.InternalError Connection.OperationalError Connection.ProgrammingError Connection.IntegrityError Connection.DataError Connection.NotSupportedError All of the standard database exception types are accessible via connection instances. This is a DBAPI 2.0 extension. Accessing any of these attributes will generate the warning ``DB-API extension connection.DatabaseError used``. """ # DBAPI Extension: supply exceptions as attributes on the connection Warning = property(lambda self: self._getError(Warning)) Error = property(lambda self: self._getError(Error)) InterfaceError = property(lambda self: self._getError(InterfaceError)) DatabaseError = property(lambda self: self._getError(DatabaseError)) OperationalError = property(lambda self: self._getError(OperationalError)) IntegrityError = property(lambda self: self._getError(IntegrityError)) InternalError = property(lambda self: self._getError(InternalError)) ProgrammingError = property(lambda self: self._getError(ProgrammingError)) NotSupportedError = property( lambda self: self._getError(NotSupportedError)) # Determines the number of rows to read from the database server at once. # Reading more rows increases performance at the cost of memory. The # default value is 100 rows. The effect of this parameter is transparent. # That is, the library reads more rows when the cache is empty # automatically. _row_cache_size = 100 _row_cache_size_bin = i_pack(_row_cache_size) def _getError(self, error): warn( "DB-API extension connection.%s used" % error.__name__, stacklevel=3) return error def __init__( self, user, host, unix_sock, port, database, password, ssl, timeout): self._client_encoding = "utf8" self._commands_with_count = ( b("INSERT"), b("DELETE"), b("UPDATE"), b("MOVE"), b("FETCH"), b("COPY"), b("SELECT")) self._lock = threading.Lock() if user is None: raise InterfaceError( "The 'user' connection parameter cannot be None") if isinstance(user, text_type): self.user = user.encode('utf8') else: self.user = user if isinstance(password, text_type): self.password = password.encode('utf8') else: self.password = password self.autocommit = False self._xid = None self._caches = defaultdict(lambda: defaultdict(dict)) self.statement_number = 0 self.portal_number = 0 try: if unix_sock is None and host is not None: self._usock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) elif unix_sock is not None: if not hasattr(socket, "AF_UNIX"): raise InterfaceError( "attempt to connect to unix socket on unsupported " "platform") self._usock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) else: raise ProgrammingError( "one of host or unix_sock must be provided") if not PY2 and timeout is not None: self._usock.settimeout(timeout) if unix_sock is None and host is not None: self._usock.connect((host, port)) elif unix_sock is not None: self._usock.connect(unix_sock) if ssl: with self._lock: try: import ssl as sslmodule # Int32(8) - Message length, including self. # Int32(80877103) - The SSL request code. self._usock.sendall(ii_pack(8, 80877103)) resp = self._usock.recv(1) if resp == b('S'): self._usock = sslmodule.wrap_socket(self._usock) else: raise InterfaceError("Server refuses SSL") except ImportError: raise InterfaceError( "SSL required but ssl module not available in " "this python installation") self._sock = self._usock.makefile(mode="rwb") except socket.error as e: self._usock.close() raise InterfaceError("communication error", e) self._flush = self._sock.flush self._read = self._sock.read self._write = self._sock.write self._backend_key_data = None ## # An event handler that is fired when the database server issues a # notice. # The value of this property is a MulticastDelegate. A callback # can be added by using connection.NotificationReceived += SomeMethod. # The method will be called with a single argument, an object that has # properties: severity, code, msg, and possibly others (detail, hint, # position, where, file, line, and routine). Callbacks can be removed # with the -= operator. #

# Stability: Added in v1.03, stability guaranteed for v1.xx. self.NoticeReceived = MulticastDelegate() ## # An event handler that is fired when a runtime configuration option is # changed on the server. The value of this property is a # MulticastDelegate. A callback can be added by using # connection.NotificationReceived += SomeMethod. Callbacks can be # removed with the -= operator. The method will be called with a single # argument, an object that has properties "key" and "value". #

# Stability: Added in v1.03, stability guaranteed for v1.xx. self.ParameterStatusReceived = MulticastDelegate() ## # An event handler that is fired when NOTIFY occurs for a notification # that has been LISTEN'd for. The value of this property is a # MulticastDelegate. A callback can be added by using # connection.NotificationReceived += SomeMethod. The method will be # called with a single argument, an object that has properties: # backend_pid, condition, and additional_info. Callbacks can be # removed with the -= operator. #

# Stability: Added in v1.03, stability guaranteed for v1.xx. self.NotificationReceived = MulticastDelegate() self.ParameterStatusReceived += self.handle_PARAMETER_STATUS def text_out(v): return v.encode(self._client_encoding) def time_out(v): return v.isoformat().encode(self._client_encoding) def date_out(v): if v == datetime.date.max: return 'infinity'.encode(self._client_encoding) elif v == datetime.date.min: return '-infinity'.encode(self._client_encoding) else: return v.isoformat().encode(self._client_encoding) def unknown_out(v): return str(v).encode(self._client_encoding) trans_tab = dict(zip(map(ord, u('{}')), u('[]'))) glbls = {'Decimal': Decimal} def array_in(data, idx, length): arr = [] prev_c = None for c in data[idx:idx+length].decode( self._client_encoding).translate( trans_tab).replace(u('NULL'), u('None')): if c not in ('[', ']', ',', 'N') and prev_c in ('[', ','): arr.extend("Decimal('") elif c in (']', ',') and prev_c not in ('[', ']', ',', 'e'): arr.extend("')") arr.append(c) prev_c = c return eval(''.join(arr), glbls) def array_recv(data, idx, length): final_idx = idx + length dim, hasnull, typeoid = iii_unpack(data, idx) idx += 12 # get type conversion method for typeoid conversion = self.pg_types[typeoid][1] # Read dimension info dim_lengths = [] for i in range(dim): dim_lengths.append(ii_unpack(data, idx)[0]) idx += 8 # Read all array values values = [] while idx < final_idx: element_len, = i_unpack(data, idx) idx += 4 if element_len == -1: values.append(None) else: values.append(conversion(data, idx, element_len)) idx += element_len # at this point, {{1,2,3},{4,5,6}}::int[][] looks like # [1,2,3,4,5,6]. go through the dimensions and fix up the array # contents to match expected dimensions for length in reversed(dim_lengths[1:]): values = list(map(list, zip(*[iter(values)] * length))) return values def vector_in(data, idx, length): return eval('[' + data[idx:idx+length].decode( self._client_encoding).replace(' ', ',') + ']') if PY2: def text_recv(data, offset, length): return unicode( # noqa data[offset: offset + length], self._client_encoding) def bool_recv(d, o, l): return d[o] == "\x01" def json_in(data, offset, length): return loads(unicode( # noqa data[offset: offset + length], self._client_encoding)) else: def text_recv(data, offset, length): return str( data[offset: offset + length], self._client_encoding) def bool_recv(data, offset, length): return data[offset] == 1 def json_in(data, offset, length): return loads( str(data[offset: offset + length], self._client_encoding)) def time_in(data, offset, length): hour = int(data[offset:offset + 2]) minute = int(data[offset + 3:offset + 5]) sec = Decimal( data[offset + 6:offset + length].decode(self._client_encoding)) return datetime.time( hour, minute, int(sec), int((sec - int(sec)) * 1000000)) def date_in(data, offset, length): year_str = data[offset:offset + 4].decode(self._client_encoding) if year_str == 'infi': return datetime.date.max elif year_str == '-inf': return datetime.date.min else: return datetime.date( int(year_str), int(data[offset + 5:offset + 7]), int(data[offset + 8:offset + 10])) def numeric_in(data, offset, length): return Decimal( data[offset: offset + length].decode(self._client_encoding)) def numeric_out(d): return str(d).encode(self._client_encoding) self.pg_types = defaultdict( lambda: (FC_TEXT, text_recv), { 16: (FC_BINARY, bool_recv), # boolean 17: (FC_BINARY, bytea_recv), # bytea 19: (FC_BINARY, text_recv), # name type 20: (FC_BINARY, int8_recv), # int8 21: (FC_BINARY, int2_recv), # int2 22: (FC_TEXT, vector_in), # int2vector 23: (FC_BINARY, int4_recv), # int4 25: (FC_BINARY, text_recv), # TEXT type 26: (FC_TEXT, int_in), # oid 28: (FC_TEXT, int_in), # xid 114: (FC_TEXT, json_in), # json 700: (FC_BINARY, float4_recv), # float4 701: (FC_BINARY, float8_recv), # float8 705: (FC_BINARY, text_recv), # unknown 829: (FC_TEXT, text_recv), # MACADDR type 1000: (FC_BINARY, array_recv), # BOOL[] 1003: (FC_BINARY, array_recv), # NAME[] 1005: (FC_BINARY, array_recv), # INT2[] 1007: (FC_BINARY, array_recv), # INT4[] 1009: (FC_BINARY, array_recv), # TEXT[] 1014: (FC_BINARY, array_recv), # CHAR[] 1015: (FC_BINARY, array_recv), # VARCHAR[] 1016: (FC_BINARY, array_recv), # INT8[] 1021: (FC_BINARY, array_recv), # FLOAT4[] 1022: (FC_BINARY, array_recv), # FLOAT8[] 1042: (FC_BINARY, text_recv), # CHAR type 1043: (FC_BINARY, text_recv), # VARCHAR type 1082: (FC_TEXT, date_in), # date 1083: (FC_TEXT, time_in), 1114: (FC_BINARY, timestamp_recv_float), # timestamp w/ tz 1184: (FC_BINARY, timestamptz_recv_float), 1186: (FC_BINARY, interval_recv_integer), 1231: (FC_TEXT, array_in), # NUMERIC[] 1263: (FC_BINARY, array_recv), # cstring[] 1700: (FC_TEXT, numeric_in), # NUMERIC 2275: (FC_BINARY, text_recv), # cstring 2950: (FC_BINARY, uuid_recv), # uuid 3802: (FC_TEXT, json_in), # jsonb }) self.py_types = { type(None): (-1, FC_BINARY, null_send), # null bool: (16, FC_BINARY, bool_send), int: (705, FC_TEXT, unknown_out), float: (701, FC_BINARY, d_pack), # float8 datetime.date: (1082, FC_TEXT, date_out), # date datetime.time: (1083, FC_TEXT, time_out), # time 1114: (1114, FC_BINARY, timestamp_send_integer), # timestamp # timestamp w/ tz 1184: (1184, FC_BINARY, timestamptz_send_integer), datetime.timedelta: (1186, FC_BINARY, interval_send_integer), Interval: (1186, FC_BINARY, interval_send_integer), Decimal: (1700, FC_TEXT, numeric_out), # Decimal UUID: (2950, FC_BINARY, uuid_send), # uuid } self.inspect_funcs = { datetime.datetime: self.inspect_datetime, list: self.array_inspect, tuple: self.array_inspect, } if PY2: self.py_types[Bytea] = (17, FC_BINARY, bytea_send) # bytea self.py_types[text_type] = (705, FC_TEXT, text_out) # unknown self.py_types[str] = (705, FC_TEXT, bytea_send) # unknown self.py_types[long] = (705, FC_TEXT, unknown_out) # noqa else: self.py_types[bytes] = (17, FC_BINARY, bytea_send) # bytea self.py_types[str] = (705, FC_TEXT, text_out) # unknown try: from ipaddress import ( ip_address, IPv4Address, IPv6Address, ip_network, IPv4Network, IPv6Network) def inet_out(v): return str(v).encode(self._client_encoding) def inet_in(data, offset, length): inet_str = data[offset: offset + length].decode( self._client_encoding) if '/' in inet_str: return ip_network(inet_str, False) else: return ip_address(inet_str) self.py_types[IPv4Address] = (869, FC_TEXT, inet_out) # inet self.py_types[IPv6Address] = (869, FC_TEXT, inet_out) # inet self.py_types[IPv4Network] = (869, FC_TEXT, inet_out) # inet self.py_types[IPv6Network] = (869, FC_TEXT, inet_out) # inet self.pg_types[869] = (FC_TEXT, inet_in) # inet except ImportError: pass self.message_types = { NOTICE_RESPONSE: self.handle_NOTICE_RESPONSE, AUTHENTICATION_REQUEST: self.handle_AUTHENTICATION_REQUEST, PARAMETER_STATUS: self.handle_PARAMETER_STATUS, BACKEND_KEY_DATA: self.handle_BACKEND_KEY_DATA, READY_FOR_QUERY: self.handle_READY_FOR_QUERY, ROW_DESCRIPTION: self.handle_ROW_DESCRIPTION, ERROR_RESPONSE: self.handle_ERROR_RESPONSE, EMPTY_QUERY_RESPONSE: self.handle_EMPTY_QUERY_RESPONSE, DATA_ROW: self.handle_DATA_ROW, COMMAND_COMPLETE: self.handle_COMMAND_COMPLETE, PARSE_COMPLETE: self.handle_PARSE_COMPLETE, BIND_COMPLETE: self.handle_BIND_COMPLETE, CLOSE_COMPLETE: self.handle_CLOSE_COMPLETE, PORTAL_SUSPENDED: self.handle_PORTAL_SUSPENDED, NO_DATA: self.handle_NO_DATA, PARAMETER_DESCRIPTION: self.handle_PARAMETER_DESCRIPTION, NOTIFICATION_RESPONSE: self.handle_NOTIFICATION_RESPONSE, COPY_DONE: self.handle_COPY_DONE, COPY_DATA: self.handle_COPY_DATA, COPY_IN_RESPONSE: self.handle_COPY_IN_RESPONSE, COPY_OUT_RESPONSE: self.handle_COPY_OUT_RESPONSE} # Int32 - Message length, including self. # Int32(196608) - Protocol version number. Version 3.0. # Any number of key/value pairs, terminated by a zero byte: # String - A parameter name (user, database, or options) # String - Parameter value protocol = 196608 val = bytearray( i_pack(protocol) + b("user\x00") + self.user + NULL_BYTE) if database is not None: if isinstance(database, text_type): database = database.encode('utf8') val.extend(b("database\x00") + database + NULL_BYTE) val.append(0) self._write(i_pack(len(val) + 4)) self._write(val) self._flush() self._cursor = self.cursor() with self._lock: try: code = self.error = None while code not in (READY_FOR_QUERY, ERROR_RESPONSE): code, data_len = ci_unpack(self._read(5)) self.message_types[code](self._read(data_len - 4), None) if self.error is not None: raise self.error except Exception as e: try: self._close() except Exception: pass raise e self.in_transaction = False self.notifies = [] self.notifies_lock = threading.Lock() def handle_ERROR_RESPONSE(self, data, ps): responses = tuple( (s[0:1], s[1:].decode(self._client_encoding)) for s in data.split(NULL_BYTE)) msg_dict = dict(responses) if msg_dict[RESPONSE_CODE] == "28000": self.error = InterfaceError("md5 password authentication failed") else: self.error = ProgrammingError(*tuple(v for k, v in responses)) def handle_EMPTY_QUERY_RESPONSE(self, data, ps): self.error = ProgrammingError("query was empty") def handle_CLOSE_COMPLETE(self, data, ps): pass def handle_PARSE_COMPLETE(self, data, ps): # Byte1('1') - Identifier. # Int32(4) - Message length, including self. pass def handle_BIND_COMPLETE(self, data, ps): pass def handle_PORTAL_SUSPENDED(self, data, cursor): cursor.portal_suspended = True def handle_PARAMETER_DESCRIPTION(self, data, ps): # Well, we don't really care -- we're going to send whatever we # want and let the database deal with it. But thanks anyways! # count = h_unpack(data)[0] # type_oids = unpack_from("!" + "i" * count, data, 2) pass def handle_COPY_DONE(self, data, ps): self._copy_done = True def handle_COPY_OUT_RESPONSE(self, data, ps): # Int8(1) - 0 textual, 1 binary # Int16(2) - Number of columns # Int16(N) - Format codes for each column (0 text, 1 binary) is_binary, num_cols = bh_unpack(data) # column_formats = unpack_from('!' + 'h' * num_cols, data, 3) if ps.stream is None: raise InterfaceError( "An output stream is required for the COPY OUT response.") def handle_COPY_DATA(self, data, ps): ps.stream.write(data) def handle_COPY_IN_RESPONSE(self, data, ps): # Int16(2) - Number of columns # Int16(N) - Format codes for each column (0 text, 1 binary) is_binary, num_cols = bh_unpack(data) # column_formats = unpack_from('!' + 'h' * num_cols, data, 3) assert self._lock.locked() if ps.stream is None: raise InterfaceError( "An input stream is required for the COPY IN response.") if PY2: while True: data = ps.stream.read(8192) if not data: break self._write(COPY_DATA + i_pack(len(data) + 4)) self._write(data) self._flush() else: bffr = bytearray(8192) while True: bytes_read = ps.stream.readinto(bffr) if bytes_read == 0: break self._write(COPY_DATA + i_pack(bytes_read + 4)) self._write(bffr[:bytes_read]) self._flush() # Send CopyDone # Byte1('c') - Identifier. # Int32(4) - Message length, including self. self._write(COPY_DONE_MSG) self._write(SYNC_MSG) self._flush() def handle_NOTIFICATION_RESPONSE(self, data, ps): self.NotificationReceived(data) ## # A message sent if this connection receives a NOTIFY that it was # LISTENing for. #

# Stability: Added in pg8000 v1.03. When limited to accessing # properties from a notification event dispatch, stability is # guaranteed for v1.xx. backend_pid = i_unpack(data)[0] idx = 4 null = data.find(NULL_BYTE, idx) - idx condition = data[idx:idx + null].decode("ascii") idx += null + 1 null = data.find(NULL_BYTE, idx) - idx # additional_info = data[idx:idx + null] # psycopg2 compatible notification interface with self.notifies_lock: self.notifies.append((backend_pid, condition)) def cursor(self): """Creates a :class:`Cursor` object bound to this connection. This function is part of the `DBAPI 2.0 specification `_. """ return Cursor(self) def commit(self): """Commits the current database transaction. This function is part of the `DBAPI 2.0 specification `_. """ with self._lock: self.execute(self._cursor, "commit", None) def rollback(self): """Rolls back the current database transaction. This function is part of the `DBAPI 2.0 specification `_. """ with self._lock: self.execute(self._cursor, "rollback", None) def _close(self): try: # Byte1('X') - Identifies the message as a terminate message. # Int32(4) - Message length, including self. self._write(TERMINATE_MSG) self._flush() self._sock.close() except AttributeError: raise InterfaceError("connection is closed") except ValueError: raise InterfaceError("connection is closed") except socket.error as e: raise OperationalError(str(e)) finally: self._usock.close() self._sock = None def close(self): """Closes the database connection. This function is part of the `DBAPI 2.0 specification `_. """ with self._lock: self._close() def handle_AUTHENTICATION_REQUEST(self, data, cursor): assert self._lock.locked() # Int32 - An authentication code that represents different # authentication messages: # 0 = AuthenticationOk # 5 = MD5 pwd # 2 = Kerberos v5 (not supported by pg8000) # 3 = Cleartext pwd # 4 = crypt() pwd (not supported by pg8000) # 6 = SCM credential (not supported by pg8000) # 7 = GSSAPI (not supported by pg8000) # 8 = GSSAPI data (not supported by pg8000) # 9 = SSPI (not supported by pg8000) # Some authentication messages have additional data following the # authentication code. That data is documented in the appropriate # class. auth_code = i_unpack(data)[0] if auth_code == 0: pass elif auth_code == 3: if self.password is None: raise InterfaceError( "server requesting password authentication, but no " "password was provided") self._send_message(PASSWORD, self.password + NULL_BYTE) self._flush() elif auth_code == 5: ## # A message representing the backend requesting an MD5 hashed # password response. The response will be sent as # md5(md5(pwd + login) + salt). # Additional message data: # Byte4 - Hash salt. salt = b("").join(cccc_unpack(data, 4)) if self.password is None: raise InterfaceError( "server requesting MD5 password authentication, but no " "password was provided") pwd = b("md5") + md5( md5(self.password + self.user).hexdigest().encode("ascii") + salt).hexdigest().encode("ascii") # Byte1('p') - Identifies the message as a password message. # Int32 - Message length including self. # String - The password. Password may be encrypted. self._send_message(PASSWORD, pwd + NULL_BYTE) self._flush() elif auth_code in (2, 4, 6, 7, 8, 9): raise InterfaceError( "Authentication method " + str(auth_code) + " not supported by pg8000.") else: raise InterfaceError( "Authentication method " + str(auth_code) + " not recognized by pg8000.") def handle_READY_FOR_QUERY(self, data, ps): # Byte1 - Status indicator. self.in_transaction = data != IDLE def handle_BACKEND_KEY_DATA(self, data, ps): self._backend_key_data = data def inspect_datetime(self, value): if value.tzinfo is None: return self.py_types[1114] # timestamp else: return self.py_types[1184] # send as timestamptz def make_params(self, values): params = [] for value in values: typ = type(value) try: params.append(self.py_types[typ]) except KeyError: try: params.append(self.inspect_funcs[typ](value)) except KeyError as e: raise NotSupportedError( "type " + str(e) + "not mapped to pg type") return tuple(params) def handle_ROW_DESCRIPTION(self, data, cursor): count = h_unpack(data)[0] idx = 2 for i in range(count): name = data[idx:data.find(NULL_BYTE, idx)] idx += len(name) + 1 field = dict( zip(( "table_oid", "column_attrnum", "type_oid", "type_size", "type_modifier", "format"), ihihih_unpack(data, idx))) field['name'] = name idx += 18 cursor.ps['row_desc'].append(field) field['pg8000_fc'], field['func'] = \ self.pg_types[field['type_oid']] def execute(self, cursor, operation, vals): if vals is None: vals = () paramstyle = pg8000.paramstyle cache = self._caches[paramstyle] try: statement, make_args = cache['statement'][operation] except KeyError: statement, make_args = convert_paramstyle(paramstyle, operation) cache['statement'][operation] = statement, make_args args = make_args(vals) params = self.make_params(args) key = operation, params try: ps = cache['ps'][key] cursor.ps = ps except KeyError: statement_name = "pg8000_statement_" + str(self.statement_number) self.statement_number += 1 statement_name_bin = statement_name.encode('ascii') + NULL_BYTE ps = { 'row_desc': [], 'param_funcs': tuple(x[2] for x in params), } cursor.ps = ps param_fcs = tuple(x[1] for x in params) # Byte1('P') - Identifies the message as a Parse command. # Int32 - Message length, including self. # String - Prepared statement name. An empty string selects the # unnamed prepared statement. # String - The query string. # Int16 - Number of parameter data types specified (can be zero). # For each parameter: # Int32 - The OID of the parameter data type. val = bytearray(statement_name_bin) val.extend(statement.encode(self._client_encoding) + NULL_BYTE) val.extend(h_pack(len(params))) for oid, fc, send_func in params: # Parse message doesn't seem to handle the -1 type_oid for NULL # values that other messages handle. So we'll provide type_oid # 705, the PG "unknown" type. val.extend(i_pack(705 if oid == -1 else oid)) # Byte1('D') - Identifies the message as a describe command. # Int32 - Message length, including self. # Byte1 - 'S' for prepared statement, 'P' for portal. # String - The name of the item to describe. self._send_message(PARSE, val) self._send_message(DESCRIBE, STATEMENT + statement_name_bin) self._write(SYNC_MSG) try: self._flush() except AttributeError as e: if self._sock is None: raise InterfaceError("connection is closed") else: raise e except socket.error as e: raise OperationalError(str(e)) self.handle_messages(cursor) # We've got row_desc that allows us to identify what we're # going to get back from this statement. output_fc = tuple( self.pg_types[f['type_oid']][0] for f in ps['row_desc']) ps['input_funcs'] = tuple(f['func'] for f in ps['row_desc']) # Byte1('B') - Identifies the Bind command. # Int32 - Message length, including self. # String - Name of the destination portal. # String - Name of the source prepared statement. # Int16 - Number of parameter format codes. # For each parameter format code: # Int16 - The parameter format code. # Int16 - Number of parameter values. # For each parameter value: # Int32 - The length of the parameter value, in bytes, not # including this length. -1 indicates a NULL parameter # value, in which no value bytes follow. # Byte[n] - Value of the parameter. # Int16 - The number of result-column format codes. # For each result-column format code: # Int16 - The format code. ps['bind_1'] = statement_name_bin + h_pack(len(params)) + \ pack("!" + "h" * len(param_fcs), *param_fcs) + \ h_pack(len(params)) ps['bind_2'] = h_pack(len(output_fc)) + \ pack("!" + "h" * len(output_fc), *output_fc) cache['ps'][key] = ps cursor._cached_rows.clear() cursor._row_count = -1 cursor.portal_name = "pg8000_portal_" + str(self.portal_number) self.portal_number += 1 cursor.portal_name_bin = cursor.portal_name.encode('ascii') + NULL_BYTE cursor.execute_msg = cursor.portal_name_bin + \ Connection._row_cache_size_bin # Byte1('B') - Identifies the Bind command. # Int32 - Message length, including self. # String - Name of the destination portal. # String - Name of the source prepared statement. # Int16 - Number of parameter format codes. # For each parameter format code: # Int16 - The parameter format code. # Int16 - Number of parameter values. # For each parameter value: # Int32 - The length of the parameter value, in bytes, not # including this length. -1 indicates a NULL parameter # value, in which no value bytes follow. # Byte[n] - Value of the parameter. # Int16 - The number of result-column format codes. # For each result-column format code: # Int16 - The format code. retval = bytearray(cursor.portal_name_bin + ps['bind_1']) for value, send_func in zip(args, ps['param_funcs']): if value is None: val = NULL else: val = send_func(value) retval.extend(i_pack(len(val))) retval.extend(val) retval.extend(ps['bind_2']) self._send_message(BIND, retval) self.send_EXECUTE(cursor) self._write(SYNC_MSG) self._flush() self.handle_messages(cursor) if cursor.portal_suspended: if self.autocommit: raise InterfaceError( "With autocommit on, it's not possible to retrieve more " "rows than the pg8000 cache size, as the portal is closed " "when the transaction is closed.") else: self.close_portal(cursor) def _send_message(self, code, data): try: self._write(code) self._write(i_pack(len(data) + 4)) self._write(data) self._write(FLUSH_MSG) except ValueError as e: if str(e) == "write to closed file": raise InterfaceError("connection is closed") else: raise e except AttributeError: raise InterfaceError("connection is closed") def send_EXECUTE(self, cursor): # Byte1('E') - Identifies the message as an execute message. # Int32 - Message length, including self. # String - The name of the portal to execute. # Int32 - Maximum number of rows to return, if portal # contains a query # that returns rows. # 0 = no limit. cursor.portal_suspended = False self._send_message(EXECUTE, cursor.execute_msg) def handle_NO_DATA(self, msg, ps): pass def handle_COMMAND_COMPLETE(self, data, cursor): values = data[:-1].split(BINARY_SPACE) command = values[0] if command in self._commands_with_count: row_count = int(values[-1]) if cursor._row_count == -1: cursor._row_count = row_count else: cursor._row_count += row_count if command in DDL_COMMANDS: for k in self._caches: self._caches[k]['ps'].clear() def handle_DATA_ROW(self, data, cursor): data_idx = 2 row = [] for func in cursor.ps['input_funcs']: vlen = i_unpack(data, data_idx)[0] data_idx += 4 if vlen == -1: row.append(None) else: row.append(func(data, data_idx, vlen)) data_idx += vlen cursor._cached_rows.append(row) def handle_messages(self, cursor): code = self.error = None try: while code != READY_FOR_QUERY: code, data_len = ci_unpack(self._read(5)) self.message_types[code](self._read(data_len - 4), cursor) except: self._close() raise if self.error is not None: raise self.error # Byte1('C') - Identifies the message as a close command. # Int32 - Message length, including self. # Byte1 - 'S' for prepared statement, 'P' for portal. # String - The name of the item to close. def close_portal(self, cursor): self._send_message(CLOSE, PORTAL + cursor.portal_name_bin) self._write(SYNC_MSG) self._flush() self.handle_messages(cursor) # Byte1('N') - Identifier # Int32 - Message length # Any number of these, followed by a zero byte: # Byte1 - code identifying the field type (see responseKeys) # String - field value def handle_NOTICE_RESPONSE(self, data, ps): resp = dict((s[0:1], s[1:]) for s in data.split(NULL_BYTE)) self.NoticeReceived(resp) def handle_PARAMETER_STATUS(self, data, ps): pos = data.find(NULL_BYTE) key, value = data[:pos], data[pos + 1:-1] if key == b("client_encoding"): encoding = value.decode("ascii").lower() self._client_encoding = pg_to_py_encodings.get(encoding, encoding) elif key == b("integer_datetimes"): if value == b('on'): self.py_types[1114] = (1114, FC_BINARY, timestamp_send_integer) self.pg_types[1114] = (FC_BINARY, timestamp_recv_integer) self.py_types[1184] = ( 1184, FC_BINARY, timestamptz_send_integer) self.pg_types[1184] = (FC_BINARY, timestamptz_recv_integer) self.py_types[Interval] = ( 1186, FC_BINARY, interval_send_integer) self.py_types[datetime.timedelta] = ( 1186, FC_BINARY, interval_send_integer) self.pg_types[1186] = (FC_BINARY, interval_recv_integer) else: self.py_types[1114] = (1114, FC_BINARY, timestamp_send_float) self.pg_types[1114] = (FC_BINARY, timestamp_recv_float) self.py_types[1184] = (1184, FC_BINARY, timestamptz_send_float) self.pg_types[1184] = (FC_BINARY, timestamptz_recv_float) self.py_types[Interval] = ( 1186, FC_BINARY, interval_send_float) self.py_types[datetime.timedelta] = ( 1186, FC_BINARY, interval_send_float) self.pg_types[1186] = (FC_BINARY, interval_recv_float) elif key == b("server_version"): self._server_version = LooseVersion(value.decode('ascii')) if self._server_version < LooseVersion('8.2.0'): self._commands_with_count = ( b("INSERT"), b("DELETE"), b("UPDATE"), b("MOVE"), b("FETCH")) elif self._server_version < LooseVersion('9.0.0'): self._commands_with_count = ( b("INSERT"), b("DELETE"), b("UPDATE"), b("MOVE"), b("FETCH"), b("COPY")) def array_inspect(self, value): # Check if array has any values. If not, we can't determine the proper # array oid. first_element = array_find_first_element(value) if first_element is None: raise ArrayContentEmptyError("array has no values") # supported array output typ = type(first_element) if issubclass(typ, integer_types): # special int array support -- send as smallest possible array type typ = integer_types int2_ok, int4_ok, int8_ok = True, True, True for v in array_flatten(value): if v is None: continue if min_int2 < v < max_int2: continue int2_ok = False if min_int4 < v < max_int4: continue int4_ok = False if min_int8 < v < max_int8: continue int8_ok = False if int2_ok: array_oid = 1005 # INT2[] oid, fc, send_func = (21, FC_BINARY, h_pack) elif int4_ok: array_oid = 1007 # INT4[] oid, fc, send_func = (23, FC_BINARY, i_pack) elif int8_ok: array_oid = 1016 # INT8[] oid, fc, send_func = (20, FC_BINARY, q_pack) else: raise ArrayContentNotSupportedError( "numeric not supported as array contents") else: try: oid, fc, send_func = self.make_params((first_element,))[0] # If unknown, assume it's a string array if oid == 705: oid = 25 # Use binary ARRAY format to avoid having to properly # escape text in the array literals fc = FC_BINARY array_oid = pg_array_types[oid] except KeyError: raise ArrayContentNotSupportedError( "oid " + str(oid) + " not supported as array contents") except NotSupportedError: raise ArrayContentNotSupportedError( "type " + str(typ) + " not supported as array contents") if fc == FC_BINARY: def send_array(arr): # check for homogenous array for a, i, v in walk_array(arr): if not isinstance(v, (typ, type(None))): raise ArrayContentNotHomogenousError( "not all array elements are of type " + str(typ)) # check that all array dimensions are consistent array_check_dimensions(arr) has_null = array_has_null(arr) dim_lengths = array_dim_lengths(arr) data = bytearray(iii_pack(len(dim_lengths), has_null, oid)) for i in dim_lengths: data.extend(ii_pack(i, 1)) for v in array_flatten(arr): if v is None: data += i_pack(-1) else: inner_data = send_func(v) data += i_pack(len(inner_data)) data += inner_data return data else: def send_array(arr): for a, i, v in walk_array(arr): if not isinstance(v, (typ, type(None))): raise ArrayContentNotHomogenousError( "not all array elements are of type " + str(typ)) array_check_dimensions(arr) ar = deepcopy(arr) for a, i, v in walk_array(ar): if v is None: a[i] = 'NULL' else: a[i] = send_func(v).decode('ascii') return u(str(ar)).translate(arr_trans).encode('ascii') return (array_oid, fc, send_array) def xid(self, format_id, global_transaction_id, branch_qualifier): """Create a Transaction IDs (only global_transaction_id is used in pg) format_id and branch_qualifier are not used in postgres global_transaction_id may be any string identifier supported by postgres returns a tuple (format_id, global_transaction_id, branch_qualifier)""" return (format_id, global_transaction_id, branch_qualifier) def tpc_begin(self, xid): """Begins a TPC transaction with the given transaction ID xid. This method should be called outside of a transaction (i.e. nothing may have executed since the last .commit() or .rollback()). Furthermore, it is an error to call .commit() or .rollback() within the TPC transaction. A ProgrammingError is raised, if the application calls .commit() or .rollback() during an active TPC transaction. This function is part of the `DBAPI 2.0 specification `_. """ self._xid = xid if self.autocommit: self.execute(self._cursor, "begin transaction", None) def tpc_prepare(self): """Performs the first phase of a transaction started with .tpc_begin(). A ProgrammingError is be raised if this method is called outside of a TPC transaction. After calling .tpc_prepare(), no statements can be executed until .tpc_commit() or .tpc_rollback() have been called. This function is part of the `DBAPI 2.0 specification `_. """ q = "PREPARE TRANSACTION '%s';" % (self._xid[1],) self.execute(self._cursor, q, None) def tpc_commit(self, xid=None): """When called with no arguments, .tpc_commit() commits a TPC transaction previously prepared with .tpc_prepare(). If .tpc_commit() is called prior to .tpc_prepare(), a single phase commit is performed. A transaction manager may choose to do this if only a single resource is participating in the global transaction. When called with a transaction ID xid, the database commits the given transaction. If an invalid transaction ID is provided, a ProgrammingError will be raised. This form should be called outside of a transaction, and is intended for use in recovery. On return, the TPC transaction is ended. This function is part of the `DBAPI 2.0 specification `_. """ if xid is None: xid = self._xid if xid is None: raise ProgrammingError( "Cannot tpc_commit() without a TPC transaction!") try: previous_autocommit_mode = self.autocommit self.autocommit = True if xid in self.tpc_recover(): self.execute( self._cursor, "COMMIT PREPARED '%s';" % (xid[1], ), None) else: # a single-phase commit self.commit() finally: self.autocommit = previous_autocommit_mode self._xid = None def tpc_rollback(self, xid=None): """When called with no arguments, .tpc_rollback() rolls back a TPC transaction. It may be called before or after .tpc_prepare(). When called with a transaction ID xid, it rolls back the given transaction. If an invalid transaction ID is provided, a ProgrammingError is raised. This form should be called outside of a transaction, and is intended for use in recovery. On return, the TPC transaction is ended. This function is part of the `DBAPI 2.0 specification `_. """ if xid is None: xid = self._xid if xid is None: raise ProgrammingError( "Cannot tpc_rollback() without a TPC prepared transaction!") try: previous_autocommit_mode = self.autocommit self.autocommit = True if xid in self.tpc_recover(): # a two-phase rollback self.execute( self._cursor, "ROLLBACK PREPARED '%s';" % (xid[1],), None) else: # a single-phase rollback self.rollback() finally: self.autocommit = previous_autocommit_mode self._xid = None def tpc_recover(self): """Returns a list of pending transaction IDs suitable for use with .tpc_commit(xid) or .tpc_rollback(xid). This function is part of the `DBAPI 2.0 specification `_. """ try: previous_autocommit_mode = self.autocommit self.autocommit = True curs = self.cursor() curs.execute("select gid FROM pg_prepared_xacts") return [self.xid(0, row[0], '') for row in curs] finally: self.autocommit = previous_autocommit_mode # pg element oid -> pg array typeoid pg_array_types = { 16: 1000, 25: 1009, # TEXT[] 701: 1022, 1700: 1231, # NUMERIC[] } # PostgreSQL encodings: # http://www.postgresql.org/docs/8.3/interactive/multibyte.html # Python encodings: # http://www.python.org/doc/2.4/lib/standard-encodings.html # # Commented out encodings don't require a name change between PostgreSQL and # Python. If the py side is None, then the encoding isn't supported. pg_to_py_encodings = { # Not supported: "mule_internal": None, "euc_tw": None, # Name fine as-is: # "euc_jp", # "euc_jis_2004", # "euc_kr", # "gb18030", # "gbk", # "johab", # "sjis", # "shift_jis_2004", # "uhc", # "utf8", # Different name: "euc_cn": "gb2312", "iso_8859_5": "is8859_5", "iso_8859_6": "is8859_6", "iso_8859_7": "is8859_7", "iso_8859_8": "is8859_8", "koi8": "koi8_r", "latin1": "iso8859-1", "latin2": "iso8859_2", "latin3": "iso8859_3", "latin4": "iso8859_4", "latin5": "iso8859_9", "latin6": "iso8859_10", "latin7": "iso8859_13", "latin8": "iso8859_14", "latin9": "iso8859_15", "sql_ascii": "ascii", "win866": "cp886", "win874": "cp874", "win1250": "cp1250", "win1251": "cp1251", "win1252": "cp1252", "win1253": "cp1253", "win1254": "cp1254", "win1255": "cp1255", "win1256": "cp1256", "win1257": "cp1257", "win1258": "cp1258", "unicode": "utf-8", # Needed for Amazon Redshift } def walk_array(arr): for i, v in enumerate(arr): if isinstance(v, list): for a, i2, v2 in walk_array(v): yield a, i2, v2 else: yield arr, i, v def array_find_first_element(arr): for v in array_flatten(arr): if v is not None: return v return None def array_flatten(arr): for v in arr: if isinstance(v, list): for v2 in array_flatten(v): yield v2 else: yield v def array_check_dimensions(arr): v0 = arr[0] if isinstance(v0, list): req_len = len(v0) req_inner_lengths = array_check_dimensions(v0) for v in arr: inner_lengths = array_check_dimensions(v) if len(v) != req_len or inner_lengths != req_inner_lengths: raise ArrayDimensionsNotConsistentError( "array dimensions not consistent") retval = [req_len] retval.extend(req_inner_lengths) return retval else: # make sure nothing else at this level is a list for v in arr: if isinstance(v, list): raise ArrayDimensionsNotConsistentError( "array dimensions not consistent") return [] def array_has_null(arr): for v in array_flatten(arr): if v is None: return True return False def array_dim_lengths(arr): v0 = arr[0] if isinstance(v0, list): retval = [len(v0)] retval.extend(array_dim_lengths(v0)) else: return [len(arr)] return retval pg8000-1.10.6/pg8000/__init__.py0000664000175000017500000001541512726505735016354 0ustar tlocketlocke00000000000000from .core import ( Warning, Bytea, DataError, DatabaseError, InterfaceError, ProgrammingError, Error, OperationalError, IntegrityError, InternalError, NotSupportedError, ArrayContentNotHomogenousError, ArrayContentEmptyError, ArrayDimensionsNotConsistentError, ArrayContentNotSupportedError, utc, Connection, Cursor, Binary, Date, DateFromTicks, Time, TimeFromTicks, Timestamp, TimestampFromTicks, BINARY, Interval) from ._version import get_versions __version__ = get_versions()['version'] del get_versions # Copyright (c) 2007-2009, Mathieu Fenniak # All rights reserved. # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright notice, # this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above copyright notice, # this list of conditions and the following disclaimer in the documentation # and/or other materials provided with the distribution. # * The name of the author may not be used to endorse or promote products # derived from this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE # ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE # LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR # CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF # SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE # POSSIBILITY OF SUCH DAMAGE. __author__ = "Mathieu Fenniak" def connect( user=None, host='localhost', unix_sock=None, port=5432, database=None, password=None, ssl=False, timeout=None, **kwargs): """Creates a connection to a PostgreSQL database. This function is part of the `DBAPI 2.0 specification `_; however, the arguments of the function are not defined by the specification. :param user: The username to connect to the PostgreSQL server with. If your server character encoding is not ``ascii`` or ``utf8``, then you need to provide ``user`` as bytes, eg. ``"my_name".encode('EUC-JP')``. :keyword host: The hostname of the PostgreSQL server to connect with. Providing this parameter is necessary for TCP/IP connections. One of either ``host`` or ``unix_sock`` must be provided. The default is ``localhost``. :keyword unix_sock: The path to the UNIX socket to access the database through, for example, ``'/tmp/.s.PGSQL.5432'``. One of either ``host`` or ``unix_sock`` must be provided. :keyword port: The TCP/IP port of the PostgreSQL server instance. This parameter defaults to ``5432``, the registered common port of PostgreSQL TCP/IP servers. :keyword database: The name of the database instance to connect with. This parameter is optional; if omitted, the PostgreSQL server will assume the database name is the same as the username. If your server character encoding is not ``ascii`` or ``utf8``, then you need to provide ``database`` as bytes, eg. ``"my_db".encode('EUC-JP')``. :keyword password: The user password to connect to the server with. This parameter is optional; if omitted and the database server requests password-based authentication, the connection will fail to open. If this parameter is provided but not requested by the server, no error will occur. If your server character encoding is not ``ascii`` or ``utf8``, then you need to provide ``user`` as bytes, eg. ``"my_password".encode('EUC-JP')``. :keyword ssl: Use SSL encryption for TCP/IP sockets if ``True``. Defaults to ``False``. :keyword timeout: Only used with Python 3, this is the time in seconds before the connection to the database will time out. The default is ``None`` which means no timeout. :rtype: A :class:`Connection` object. """ return Connection( user, host, unix_sock, port, database, password, ssl, timeout) apilevel = "2.0" """The DBAPI level supported, currently "2.0". This property is part of the `DBAPI 2.0 specification `_. """ threadsafety = 3 """Integer constant stating the level of thread safety the DBAPI interface supports. This DBAPI module supports sharing the module, connections, and cursors, resulting in a threadsafety value of 3. This property is part of the `DBAPI 2.0 specification `_. """ paramstyle = 'format' """String property stating the type of parameter marker formatting expected by the interface. This value defaults to "format", in which parameters are marked in this format: "WHERE name=%s". This property is part of the `DBAPI 2.0 specification `_. As an extension to the DBAPI specification, this value is not constant; it can be changed to any of the following values: qmark Question mark style, eg. ``WHERE name=?`` numeric Numeric positional style, eg. ``WHERE name=:1`` named Named style, eg. ``WHERE name=:paramname`` format printf format codes, eg. ``WHERE name=%s`` pyformat Python format codes, eg. ``WHERE name=%(paramname)s`` """ # I have no idea what this would be used for by a client app. Should it be # TEXT, VARCHAR, CHAR? It will only compare against row_description's # type_code if it is this one type. It is the varchar type oid for now, this # appears to match expectations in the DB API 2.0 compliance test suite. STRING = 1043 """String type oid.""" NUMBER = 1700 """Numeric type oid""" DATETIME = 1114 """Timestamp type oid""" ROWID = 26 """ROWID type oid""" __all__ = [ Warning, Bytea, DataError, DatabaseError, connect, InterfaceError, ProgrammingError, Error, OperationalError, IntegrityError, InternalError, NotSupportedError, ArrayContentNotHomogenousError, ArrayContentEmptyError, ArrayDimensionsNotConsistentError, ArrayContentNotSupportedError, utc, Connection, Cursor, Binary, Date, DateFromTicks, Time, TimeFromTicks, Timestamp, TimestampFromTicks, BINARY, Interval] """Version string for pg8000. .. versionadded:: 1.9.11 """ pg8000-1.10.6/LICENSE0000664000175000017500000000263612720663214014322 0ustar tlocketlocke00000000000000Copyright (c) 2007-2009, Mathieu Fenniak All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. pg8000-1.10.6/versioneer.py0000664000175000017500000017201212720663214016044 0ustar tlocketlocke00000000000000 # Version: 0.15 """ The Versioneer ============== * like a rocketeer, but for versions! * https://github.com/warner/python-versioneer * Brian Warner * License: Public Domain * Compatible With: python2.6, 2.7, 3.2, 3.3, 3.4, and pypy * [![Latest Version] (https://pypip.in/version/versioneer/badge.svg?style=flat) ](https://pypi.python.org/pypi/versioneer/) * [![Build Status] (https://travis-ci.org/warner/python-versioneer.png?branch=master) ](https://travis-ci.org/warner/python-versioneer) This is a tool for managing a recorded version number in distutils-based python projects. The goal is to remove the tedious and error-prone "update the embedded version string" step from your release process. Making a new release should be as easy as recording a new tag in your version-control system, and maybe making new tarballs. ## Quick Install * `pip install versioneer` to somewhere to your $PATH * add a `[versioneer]` section to your setup.cfg (see below) * run `versioneer install` in your source tree, commit the results ## Version Identifiers Source trees come from a variety of places: * a version-control system checkout (mostly used by developers) * a nightly tarball, produced by build automation * a snapshot tarball, produced by a web-based VCS browser, like github's "tarball from tag" feature * a release tarball, produced by "setup.py sdist", distributed through PyPI Within each source tree, the version identifier (either a string or a number, this tool is format-agnostic) can come from a variety of places: * ask the VCS tool itself, e.g. "git describe" (for checkouts), which knows about recent "tags" and an absolute revision-id * the name of the directory into which the tarball was unpacked * an expanded VCS keyword ($Id$, etc) * a `_version.py` created by some earlier build step For released software, the version identifier is closely related to a VCS tag. Some projects use tag names that include more than just the version string (e.g. "myproject-1.2" instead of just "1.2"), in which case the tool needs to strip the tag prefix to extract the version identifier. For unreleased software (between tags), the version identifier should provide enough information to help developers recreate the same tree, while also giving them an idea of roughly how old the tree is (after version 1.2, before version 1.3). Many VCS systems can report a description that captures this, for example `git describe --tags --dirty --always` reports things like "0.7-1-g574ab98-dirty" to indicate that the checkout is one revision past the 0.7 tag, has a unique revision id of "574ab98", and is "dirty" (it has uncommitted changes. The version identifier is used for multiple purposes: * to allow the module to self-identify its version: `myproject.__version__` * to choose a name and prefix for a 'setup.py sdist' tarball ## Theory of Operation Versioneer works by adding a special `_version.py` file into your source tree, where your `__init__.py` can import it. This `_version.py` knows how to dynamically ask the VCS tool for version information at import time. `_version.py` also contains `$Revision$` markers, and the installation process marks `_version.py` to have this marker rewritten with a tag name during the `git archive` command. As a result, generated tarballs will contain enough information to get the proper version. To allow `setup.py` to compute a version too, a `versioneer.py` is added to the top level of your source tree, next to `setup.py` and the `setup.cfg` that configures it. This overrides several distutils/setuptools commands to compute the version when invoked, and changes `setup.py build` and `setup.py sdist` to replace `_version.py` with a small static file that contains just the generated version data. ## Installation First, decide on values for the following configuration variables: * `VCS`: the version control system you use. Currently accepts "git". * `style`: the style of version string to be produced. See "Styles" below for details. Defaults to "pep440", which looks like `TAG[+DISTANCE.gSHORTHASH[.dirty]]`. * `versionfile_source`: A project-relative pathname into which the generated version strings should be written. This is usually a `_version.py` next to your project's main `__init__.py` file, so it can be imported at runtime. If your project uses `src/myproject/__init__.py`, this should be `src/myproject/_version.py`. This file should be checked in to your VCS as usual: the copy created below by `setup.py setup_versioneer` will include code that parses expanded VCS keywords in generated tarballs. The 'build' and 'sdist' commands will replace it with a copy that has just the calculated version string. This must be set even if your project does not have any modules (and will therefore never import `_version.py`), since "setup.py sdist" -based trees still need somewhere to record the pre-calculated version strings. Anywhere in the source tree should do. If there is a `__init__.py` next to your `_version.py`, the `setup.py setup_versioneer` command (described below) will append some `__version__`-setting assignments, if they aren't already present. * `versionfile_build`: Like `versionfile_source`, but relative to the build directory instead of the source directory. These will differ when your setup.py uses 'package_dir='. If you have `package_dir={'myproject': 'src/myproject'}`, then you will probably have `versionfile_build='myproject/_version.py'` and `versionfile_source='src/myproject/_version.py'`. If this is set to None, then `setup.py build` will not attempt to rewrite any `_version.py` in the built tree. If your project does not have any libraries (e.g. if it only builds a script), then you should use `versionfile_build = None` and override `distutils.command.build_scripts` to explicitly insert a copy of `versioneer.get_version()` into your generated script. * `tag_prefix`: a string, like 'PROJECTNAME-', which appears at the start of all VCS tags. If your tags look like 'myproject-1.2.0', then you should use tag_prefix='myproject-'. If you use unprefixed tags like '1.2.0', this should be an empty string. * `parentdir_prefix`: a optional string, frequently the same as tag_prefix, which appears at the start of all unpacked tarball filenames. If your tarball unpacks into 'myproject-1.2.0', this should be 'myproject-'. To disable this feature, just omit the field from your `setup.cfg`. This tool provides one script, named `versioneer`. That script has one mode, "install", which writes a copy of `versioneer.py` into the current directory and runs `versioneer.py setup` to finish the installation. To versioneer-enable your project: * 1: Modify your `setup.cfg`, adding a section named `[versioneer]` and populating it with the configuration values you decided earlier (note that the option names are not case-sensitive): ```` [versioneer] VCS = git style = pep440 versionfile_source = src/myproject/_version.py versionfile_build = myproject/_version.py tag_prefix = "" parentdir_prefix = myproject- ```` * 2: Run `versioneer install`. This will do the following: * copy `versioneer.py` into the top of your source tree * create `_version.py` in the right place (`versionfile_source`) * modify your `__init__.py` (if one exists next to `_version.py`) to define `__version__` (by calling a function from `_version.py`) * modify your `MANIFEST.in` to include both `versioneer.py` and the generated `_version.py` in sdist tarballs `versioneer install` will complain about any problems it finds with your `setup.py` or `setup.cfg`. Run it multiple times until you have fixed all the problems. * 3: add a `import versioneer` to your setup.py, and add the following arguments to the setup() call: version=versioneer.get_version(), cmdclass=versioneer.get_cmdclass(), * 4: commit these changes to your VCS. To make sure you won't forget, `versioneer install` will mark everything it touched for addition using `git add`. Don't forget to add `setup.py` and `setup.cfg` too. ## Post-Installation Usage Once established, all uses of your tree from a VCS checkout should get the current version string. All generated tarballs should include an embedded version string (so users who unpack them will not need a VCS tool installed). If you distribute your project through PyPI, then the release process should boil down to two steps: * 1: git tag 1.0 * 2: python setup.py register sdist upload If you distribute it through github (i.e. users use github to generate tarballs with `git archive`), the process is: * 1: git tag 1.0 * 2: git push; git push --tags Versioneer will report "0+untagged.NUMCOMMITS.gHASH" until your tree has at least one tag in its history. ## Version-String Flavors Code which uses Versioneer can learn about its version string at runtime by importing `_version` from your main `__init__.py` file and running the `get_versions()` function. From the "outside" (e.g. in `setup.py`), you can import the top-level `versioneer.py` and run `get_versions()`. Both functions return a dictionary with different flavors of version information: * `['version']`: A condensed version string, rendered using the selected style. This is the most commonly used value for the project's version string. The default "pep440" style yields strings like `0.11`, `0.11+2.g1076c97`, or `0.11+2.g1076c97.dirty`. See the "Styles" section below for alternative styles. * `['full-revisionid']`: detailed revision identifier. For Git, this is the full SHA1 commit id, e.g. "1076c978a8d3cfc70f408fe5974aa6c092c949ac". * `['dirty']`: a boolean, True if the tree has uncommitted changes. Note that this is only accurate if run in a VCS checkout, otherwise it is likely to be False or None * `['error']`: if the version string could not be computed, this will be set to a string describing the problem, otherwise it will be None. It may be useful to throw an exception in setup.py if this is set, to avoid e.g. creating tarballs with a version string of "unknown". Some variants are more useful than others. Including `full-revisionid` in a bug report should allow developers to reconstruct the exact code being tested (or indicate the presence of local changes that should be shared with the developers). `version` is suitable for display in an "about" box or a CLI `--version` output: it can be easily compared against release notes and lists of bugs fixed in various releases. The installer adds the following text to your `__init__.py` to place a basic version in `YOURPROJECT.__version__`: from ._version import get_versions __version__ = get_versions()['version'] del get_versions ## Styles The setup.cfg `style=` configuration controls how the VCS information is rendered into a version string. The default style, "pep440", produces a PEP440-compliant string, equal to the un-prefixed tag name for actual releases, and containing an additional "local version" section with more detail for in-between builds. For Git, this is TAG[+DISTANCE.gHEX[.dirty]] , using information from `git describe --tags --dirty --always`. For example "0.11+2.g1076c97.dirty" indicates that the tree is like the "1076c97" commit but has uncommitted changes (".dirty"), and that this commit is two revisions ("+2") beyond the "0.11" tag. For released software (exactly equal to a known tag), the identifier will only contain the stripped tag, e.g. "0.11". Other styles are available. See details.md in the Versioneer source tree for descriptions. ## Debugging Versioneer tries to avoid fatal errors: if something goes wrong, it will tend to return a version of "0+unknown". To investigate the problem, run `setup.py version`, which will run the version-lookup code in a verbose mode, and will display the full contents of `get_versions()` (including the `error` string, which may help identify what went wrong). ## Updating Versioneer To upgrade your project to a new release of Versioneer, do the following: * install the new Versioneer (`pip install -U versioneer` or equivalent) * edit `setup.cfg`, if necessary, to include any new configuration settings indicated by the release notes * re-run `versioneer install` in your source tree, to replace `SRC/_version.py` * commit any changed files ### Upgrading to 0.15 Starting with this version, Versioneer is configured with a `[versioneer]` section in your `setup.cfg` file. Earlier versions required the `setup.py` to set attributes on the `versioneer` module immediately after import. The new version will refuse to run (raising an exception during import) until you have provided the necessary `setup.cfg` section. In addition, the Versioneer package provides an executable named `versioneer`, and the installation process is driven by running `versioneer install`. In 0.14 and earlier, the executable was named `versioneer-installer` and was run without an argument. ### Upgrading to 0.14 0.14 changes the format of the version string. 0.13 and earlier used hyphen-separated strings like "0.11-2-g1076c97-dirty". 0.14 and beyond use a plus-separated "local version" section strings, with dot-separated components, like "0.11+2.g1076c97". PEP440-strict tools did not like the old format, but should be ok with the new one. ### Upgrading from 0.11 to 0.12 Nothing special. ### Upgrading from 0.10 to 0.11 You must add a `versioneer.VCS = "git"` to your `setup.py` before re-running `setup.py setup_versioneer`. This will enable the use of additional version-control systems (SVN, etc) in the future. ## Future Directions This tool is designed to make it easily extended to other version-control systems: all VCS-specific components are in separate directories like src/git/ . The top-level `versioneer.py` script is assembled from these components by running make-versioneer.py . In the future, make-versioneer.py will take a VCS name as an argument, and will construct a version of `versioneer.py` that is specific to the given VCS. It might also take the configuration arguments that are currently provided manually during installation by editing setup.py . Alternatively, it might go the other direction and include code from all supported VCS systems, reducing the number of intermediate scripts. ## License To make Versioneer easier to embed, all its code is hereby released into the public domain. The `_version.py` that it creates is also in the public domain. """ from __future__ import print_function try: import configparser except ImportError: import ConfigParser as configparser import errno import json import os import re import subprocess import sys class VersioneerConfig: pass def get_root(): # we require that all commands are run from the project root, i.e. the # directory that contains setup.py, setup.cfg, and versioneer.py . root = os.path.realpath(os.path.abspath(os.getcwd())) setup_py = os.path.join(root, "setup.py") versioneer_py = os.path.join(root, "versioneer.py") if not (os.path.exists(setup_py) or os.path.exists(versioneer_py)): # allow 'python path/to/setup.py COMMAND' root = os.path.dirname(os.path.realpath(os.path.abspath(sys.argv[0]))) setup_py = os.path.join(root, "setup.py") versioneer_py = os.path.join(root, "versioneer.py") if not (os.path.exists(setup_py) or os.path.exists(versioneer_py)): err = ("Versioneer was unable to run the project root directory. " "Versioneer requires setup.py to be executed from " "its immediate directory (like 'python setup.py COMMAND'), " "or in a way that lets it use sys.argv[0] to find the root " "(like 'python path/to/setup.py COMMAND').") raise VersioneerBadRootError(err) try: # Certain runtime workflows (setup.py install/develop in a setuptools # tree) execute all dependencies in a single python process, so # "versioneer" may be imported multiple times, and python's shared # module-import table will cache the first one. So we can't use # os.path.dirname(__file__), as that will find whichever # versioneer.py was first imported, even in later projects. me = os.path.realpath(os.path.abspath(__file__)) if os.path.splitext(me)[0] != os.path.splitext(versioneer_py)[0]: print("Warning: build in %s is using versioneer.py from %s" % (os.path.dirname(me), versioneer_py)) except NameError: pass return root def get_config_from_root(root): # This might raise EnvironmentError (if setup.cfg is missing), or # configparser.NoSectionError (if it lacks a [versioneer] section), or # configparser.NoOptionError (if it lacks "VCS="). See the docstring at # the top of versioneer.py for instructions on writing your setup.cfg . setup_cfg = os.path.join(root, "setup.cfg") parser = configparser.SafeConfigParser() with open(setup_cfg, "r") as f: parser.readfp(f) VCS = parser.get("versioneer", "VCS") # mandatory def get(parser, name): if parser.has_option("versioneer", name): return parser.get("versioneer", name) return None cfg = VersioneerConfig() cfg.VCS = VCS cfg.style = get(parser, "style") or "" cfg.versionfile_source = get(parser, "versionfile_source") cfg.versionfile_build = get(parser, "versionfile_build") cfg.tag_prefix = get(parser, "tag_prefix") cfg.parentdir_prefix = get(parser, "parentdir_prefix") cfg.verbose = get(parser, "verbose") return cfg class NotThisMethod(Exception): pass # these dictionaries contain VCS-specific tools LONG_VERSION_PY = {} HANDLERS = {} def register_vcs_handler(vcs, method): # decorator def decorate(f): if vcs not in HANDLERS: HANDLERS[vcs] = {} HANDLERS[vcs][method] = f return f return decorate def run_command(commands, args, cwd=None, verbose=False, hide_stderr=False): assert isinstance(commands, list) p = None for c in commands: try: dispcmd = str([c] + args) # remember shell=False, so use git.cmd on windows, not just git p = subprocess.Popen([c] + args, cwd=cwd, stdout=subprocess.PIPE, stderr=(subprocess.PIPE if hide_stderr else None)) break except EnvironmentError: e = sys.exc_info()[1] if e.errno == errno.ENOENT: continue if verbose: print("unable to run %s" % dispcmd) print(e) return None else: if verbose: print("unable to find command, tried %s" % (commands,)) return None stdout = p.communicate()[0].strip() if sys.version_info[0] >= 3: stdout = stdout.decode() if p.returncode != 0: if verbose: print("unable to run %s (error)" % dispcmd) return None return stdout LONG_VERSION_PY['git'] = ''' # This file helps to compute a version number in source trees obtained from # git-archive tarball (such as those provided by githubs download-from-tag # feature). Distribution tarballs (built by setup.py sdist) and build # directories (produced by setup.py build) will contain a much shorter file # that just contains the computed version number. # This file is released into the public domain. Generated by # versioneer-0.15 (https://github.com/warner/python-versioneer) import errno import os import re import subprocess import sys def get_keywords(): # these strings will be replaced by git during git-archive. # setup.py/versioneer.py will grep for the variable names, so they must # each be defined on a line of their own. _version.py will just call # get_keywords(). git_refnames = "%(DOLLAR)sFormat:%%d%(DOLLAR)s" git_full = "%(DOLLAR)sFormat:%%H%(DOLLAR)s" keywords = {"refnames": git_refnames, "full": git_full} return keywords class VersioneerConfig: pass def get_config(): # these strings are filled in when 'setup.py versioneer' creates # _version.py cfg = VersioneerConfig() cfg.VCS = "git" cfg.style = "%(STYLE)s" cfg.tag_prefix = "%(TAG_PREFIX)s" cfg.parentdir_prefix = "%(PARENTDIR_PREFIX)s" cfg.versionfile_source = "%(VERSIONFILE_SOURCE)s" cfg.verbose = False return cfg class NotThisMethod(Exception): pass LONG_VERSION_PY = {} HANDLERS = {} def register_vcs_handler(vcs, method): # decorator def decorate(f): if vcs not in HANDLERS: HANDLERS[vcs] = {} HANDLERS[vcs][method] = f return f return decorate def run_command(commands, args, cwd=None, verbose=False, hide_stderr=False): assert isinstance(commands, list) p = None for c in commands: try: dispcmd = str([c] + args) # remember shell=False, so use git.cmd on windows, not just git p = subprocess.Popen([c] + args, cwd=cwd, stdout=subprocess.PIPE, stderr=(subprocess.PIPE if hide_stderr else None)) break except EnvironmentError: e = sys.exc_info()[1] if e.errno == errno.ENOENT: continue if verbose: print("unable to run %%s" %% dispcmd) print(e) return None else: if verbose: print("unable to find command, tried %%s" %% (commands,)) return None stdout = p.communicate()[0].strip() if sys.version_info[0] >= 3: stdout = stdout.decode() if p.returncode != 0: if verbose: print("unable to run %%s (error)" %% dispcmd) return None return stdout def versions_from_parentdir(parentdir_prefix, root, verbose): # Source tarballs conventionally unpack into a directory that includes # both the project name and a version string. dirname = os.path.basename(root) if not dirname.startswith(parentdir_prefix): if verbose: print("guessing rootdir is '%%s', but '%%s' doesn't start with " "prefix '%%s'" %% (root, dirname, parentdir_prefix)) raise NotThisMethod("rootdir doesn't start with parentdir_prefix") return {"version": dirname[len(parentdir_prefix):], "full-revisionid": None, "dirty": False, "error": None} @register_vcs_handler("git", "get_keywords") def git_get_keywords(versionfile_abs): # the code embedded in _version.py can just fetch the value of these # keywords. When used from setup.py, we don't want to import _version.py, # so we do it with a regexp instead. This function is not used from # _version.py. keywords = {} try: f = open(versionfile_abs, "r") for line in f.readlines(): if line.strip().startswith("git_refnames ="): mo = re.search(r'=\s*"(.*)"', line) if mo: keywords["refnames"] = mo.group(1) if line.strip().startswith("git_full ="): mo = re.search(r'=\s*"(.*)"', line) if mo: keywords["full"] = mo.group(1) f.close() except EnvironmentError: pass return keywords @register_vcs_handler("git", "keywords") def git_versions_from_keywords(keywords, tag_prefix, verbose): if not keywords: raise NotThisMethod("no keywords at all, weird") refnames = keywords["refnames"].strip() if refnames.startswith("$Format"): if verbose: print("keywords are unexpanded, not using") raise NotThisMethod("unexpanded keywords, not a git-archive tarball") refs = set([r.strip() for r in refnames.strip("()").split(",")]) # starting in git-1.8.3, tags are listed as "tag: foo-1.0" instead of # just "foo-1.0". If we see a "tag: " prefix, prefer those. TAG = "tag: " tags = set([r[len(TAG):] for r in refs if r.startswith(TAG)]) if not tags: # Either we're using git < 1.8.3, or there really are no tags. We use # a heuristic: assume all version tags have a digit. The old git %%d # expansion behaves like git log --decorate=short and strips out the # refs/heads/ and refs/tags/ prefixes that would let us distinguish # between branches and tags. By ignoring refnames without digits, we # filter out many common branch names like "release" and # "stabilization", as well as "HEAD" and "master". tags = set([r for r in refs if re.search(r'\d', r)]) if verbose: print("discarding '%%s', no digits" %% ",".join(refs-tags)) if verbose: print("likely tags: %%s" %% ",".join(sorted(tags))) for ref in sorted(tags): # sorting will prefer e.g. "2.0" over "2.0rc1" if ref.startswith(tag_prefix): r = ref[len(tag_prefix):] if verbose: print("picking %%s" %% r) return {"version": r, "full-revisionid": keywords["full"].strip(), "dirty": False, "error": None } # no suitable tags, so version is "0+unknown", but full hex is still there if verbose: print("no suitable tags, using unknown + full revision id") return {"version": "0+unknown", "full-revisionid": keywords["full"].strip(), "dirty": False, "error": "no suitable tags"} @register_vcs_handler("git", "pieces_from_vcs") def git_pieces_from_vcs(tag_prefix, root, verbose, run_command=run_command): # this runs 'git' from the root of the source tree. This only gets called # if the git-archive 'subst' keywords were *not* expanded, and # _version.py hasn't already been rewritten with a short version string, # meaning we're inside a checked out source tree. if not os.path.exists(os.path.join(root, ".git")): if verbose: print("no .git in %%s" %% root) raise NotThisMethod("no .git directory") GITS = ["git"] if sys.platform == "win32": GITS = ["git.cmd", "git.exe"] # if there is a tag, this yields TAG-NUM-gHEX[-dirty] # if there are no tags, this yields HEX[-dirty] (no NUM) describe_out = run_command(GITS, ["describe", "--tags", "--dirty", "--always", "--long"], cwd=root) # --long was added in git-1.5.5 if describe_out is None: raise NotThisMethod("'git describe' failed") describe_out = describe_out.strip() full_out = run_command(GITS, ["rev-parse", "HEAD"], cwd=root) if full_out is None: raise NotThisMethod("'git rev-parse' failed") full_out = full_out.strip() pieces = {} pieces["long"] = full_out pieces["short"] = full_out[:7] # maybe improved later pieces["error"] = None # parse describe_out. It will be like TAG-NUM-gHEX[-dirty] or HEX[-dirty] # TAG might have hyphens. git_describe = describe_out # look for -dirty suffix dirty = git_describe.endswith("-dirty") pieces["dirty"] = dirty if dirty: git_describe = git_describe[:git_describe.rindex("-dirty")] # now we have TAG-NUM-gHEX or HEX if "-" in git_describe: # TAG-NUM-gHEX mo = re.search(r'^(.+)-(\d+)-g([0-9a-f]+)$', git_describe) if not mo: # unparseable. Maybe git-describe is misbehaving? pieces["error"] = ("unable to parse git-describe output: '%%s'" %% describe_out) return pieces # tag full_tag = mo.group(1) if not full_tag.startswith(tag_prefix): if verbose: fmt = "tag '%%s' doesn't start with prefix '%%s'" print(fmt %% (full_tag, tag_prefix)) pieces["error"] = ("tag '%%s' doesn't start with prefix '%%s'" %% (full_tag, tag_prefix)) return pieces pieces["closest-tag"] = full_tag[len(tag_prefix):] # distance: number of commits since tag pieces["distance"] = int(mo.group(2)) # commit: short hex revision ID pieces["short"] = mo.group(3) else: # HEX: no tags pieces["closest-tag"] = None count_out = run_command(GITS, ["rev-list", "HEAD", "--count"], cwd=root) pieces["distance"] = int(count_out) # total number of commits return pieces def plus_or_dot(pieces): if "+" in pieces.get("closest-tag", ""): return "." return "+" def render_pep440(pieces): # now build up version string, with post-release "local version # identifier". Our goal: TAG[+DISTANCE.gHEX[.dirty]] . Note that if you # get a tagged build and then dirty it, you'll get TAG+0.gHEX.dirty # exceptions: # 1: no tags. git_describe was just HEX. 0+untagged.DISTANCE.gHEX[.dirty] if pieces["closest-tag"]: rendered = pieces["closest-tag"] if pieces["distance"] or pieces["dirty"]: rendered += plus_or_dot(pieces) rendered += "%%d.g%%s" %% (pieces["distance"], pieces["short"]) if pieces["dirty"]: rendered += ".dirty" else: # exception #1 rendered = "0+untagged.%%d.g%%s" %% (pieces["distance"], pieces["short"]) if pieces["dirty"]: rendered += ".dirty" return rendered def render_pep440_pre(pieces): # TAG[.post.devDISTANCE] . No -dirty # exceptions: # 1: no tags. 0.post.devDISTANCE if pieces["closest-tag"]: rendered = pieces["closest-tag"] if pieces["distance"]: rendered += ".post.dev%%d" %% pieces["distance"] else: # exception #1 rendered = "0.post.dev%%d" %% pieces["distance"] return rendered def render_pep440_post(pieces): # TAG[.postDISTANCE[.dev0]+gHEX] . The ".dev0" means dirty. Note that # .dev0 sorts backwards (a dirty tree will appear "older" than the # corresponding clean one), but you shouldn't be releasing software with # -dirty anyways. # exceptions: # 1: no tags. 0.postDISTANCE[.dev0] if pieces["closest-tag"]: rendered = pieces["closest-tag"] if pieces["distance"] or pieces["dirty"]: rendered += ".post%%d" %% pieces["distance"] if pieces["dirty"]: rendered += ".dev0" rendered += plus_or_dot(pieces) rendered += "g%%s" %% pieces["short"] else: # exception #1 rendered = "0.post%%d" %% pieces["distance"] if pieces["dirty"]: rendered += ".dev0" rendered += "+g%%s" %% pieces["short"] return rendered def render_pep440_old(pieces): # TAG[.postDISTANCE[.dev0]] . The ".dev0" means dirty. # exceptions: # 1: no tags. 0.postDISTANCE[.dev0] if pieces["closest-tag"]: rendered = pieces["closest-tag"] if pieces["distance"] or pieces["dirty"]: rendered += ".post%%d" %% pieces["distance"] if pieces["dirty"]: rendered += ".dev0" else: # exception #1 rendered = "0.post%%d" %% pieces["distance"] if pieces["dirty"]: rendered += ".dev0" return rendered def render_git_describe(pieces): # TAG[-DISTANCE-gHEX][-dirty], like 'git describe --tags --dirty # --always' # exceptions: # 1: no tags. HEX[-dirty] (note: no 'g' prefix) if pieces["closest-tag"]: rendered = pieces["closest-tag"] if pieces["distance"]: rendered += "-%%d-g%%s" %% (pieces["distance"], pieces["short"]) else: # exception #1 rendered = pieces["short"] if pieces["dirty"]: rendered += "-dirty" return rendered def render_git_describe_long(pieces): # TAG-DISTANCE-gHEX[-dirty], like 'git describe --tags --dirty # --always -long'. The distance/hash is unconditional. # exceptions: # 1: no tags. HEX[-dirty] (note: no 'g' prefix) if pieces["closest-tag"]: rendered = pieces["closest-tag"] rendered += "-%%d-g%%s" %% (pieces["distance"], pieces["short"]) else: # exception #1 rendered = pieces["short"] if pieces["dirty"]: rendered += "-dirty" return rendered def render(pieces, style): if pieces["error"]: return {"version": "unknown", "full-revisionid": pieces.get("long"), "dirty": None, "error": pieces["error"]} if not style or style == "default": style = "pep440" # the default if style == "pep440": rendered = render_pep440(pieces) elif style == "pep440-pre": rendered = render_pep440_pre(pieces) elif style == "pep440-post": rendered = render_pep440_post(pieces) elif style == "pep440-old": rendered = render_pep440_old(pieces) elif style == "git-describe": rendered = render_git_describe(pieces) elif style == "git-describe-long": rendered = render_git_describe_long(pieces) else: raise ValueError("unknown style '%%s'" %% style) return {"version": rendered, "full-revisionid": pieces["long"], "dirty": pieces["dirty"], "error": None} def get_versions(): # I am in _version.py, which lives at ROOT/VERSIONFILE_SOURCE. If we have # __file__, we can work backwards from there to the root. Some # py2exe/bbfreeze/non-CPython implementations don't do __file__, in which # case we can only use expanded keywords. cfg = get_config() verbose = cfg.verbose try: return git_versions_from_keywords(get_keywords(), cfg.tag_prefix, verbose) except NotThisMethod: pass try: root = os.path.realpath(__file__) # versionfile_source is the relative path from the top of the source # tree (where the .git directory might live) to this file. Invert # this to find the root from __file__. for i in cfg.versionfile_source.split('/'): root = os.path.dirname(root) except NameError: return {"version": "0+unknown", "full-revisionid": None, "dirty": None, "error": "unable to find root of source tree"} try: pieces = git_pieces_from_vcs(cfg.tag_prefix, root, verbose) return render(pieces, cfg.style) except NotThisMethod: pass try: if cfg.parentdir_prefix: return versions_from_parentdir(cfg.parentdir_prefix, root, verbose) except NotThisMethod: pass return {"version": "0+unknown", "full-revisionid": None, "dirty": None, "error": "unable to compute version"} ''' @register_vcs_handler("git", "get_keywords") def git_get_keywords(versionfile_abs): # the code embedded in _version.py can just fetch the value of these # keywords. When used from setup.py, we don't want to import _version.py, # so we do it with a regexp instead. This function is not used from # _version.py. keywords = {} try: f = open(versionfile_abs, "r") for line in f.readlines(): if line.strip().startswith("git_refnames ="): mo = re.search(r'=\s*"(.*)"', line) if mo: keywords["refnames"] = mo.group(1) if line.strip().startswith("git_full ="): mo = re.search(r'=\s*"(.*)"', line) if mo: keywords["full"] = mo.group(1) f.close() except EnvironmentError: pass return keywords @register_vcs_handler("git", "keywords") def git_versions_from_keywords(keywords, tag_prefix, verbose): if not keywords: raise NotThisMethod("no keywords at all, weird") refnames = keywords["refnames"].strip() if refnames.startswith("$Format"): if verbose: print("keywords are unexpanded, not using") raise NotThisMethod("unexpanded keywords, not a git-archive tarball") refs = set([r.strip() for r in refnames.strip("()").split(",")]) # starting in git-1.8.3, tags are listed as "tag: foo-1.0" instead of # just "foo-1.0". If we see a "tag: " prefix, prefer those. TAG = "tag: " tags = set([r[len(TAG):] for r in refs if r.startswith(TAG)]) if not tags: # Either we're using git < 1.8.3, or there really are no tags. We use # a heuristic: assume all version tags have a digit. The old git %d # expansion behaves like git log --decorate=short and strips out the # refs/heads/ and refs/tags/ prefixes that would let us distinguish # between branches and tags. By ignoring refnames without digits, we # filter out many common branch names like "release" and # "stabilization", as well as "HEAD" and "master". tags = set([r for r in refs if re.search(r'\d', r)]) if verbose: print("discarding '%s', no digits" % ",".join(refs-tags)) if verbose: print("likely tags: %s" % ",".join(sorted(tags))) for ref in sorted(tags): # sorting will prefer e.g. "2.0" over "2.0rc1" if ref.startswith(tag_prefix): r = ref[len(tag_prefix):] if verbose: print("picking %s" % r) return {"version": r, "full-revisionid": keywords["full"].strip(), "dirty": False, "error": None } # no suitable tags, so version is "0+unknown", but full hex is still there if verbose: print("no suitable tags, using unknown + full revision id") return {"version": "0+unknown", "full-revisionid": keywords["full"].strip(), "dirty": False, "error": "no suitable tags"} @register_vcs_handler("git", "pieces_from_vcs") def git_pieces_from_vcs(tag_prefix, root, verbose, run_command=run_command): # this runs 'git' from the root of the source tree. This only gets called # if the git-archive 'subst' keywords were *not* expanded, and # _version.py hasn't already been rewritten with a short version string, # meaning we're inside a checked out source tree. if not os.path.exists(os.path.join(root, ".git")): if verbose: print("no .git in %s" % root) raise NotThisMethod("no .git directory") GITS = ["git"] if sys.platform == "win32": GITS = ["git.cmd", "git.exe"] # if there is a tag, this yields TAG-NUM-gHEX[-dirty] # if there are no tags, this yields HEX[-dirty] (no NUM) describe_out = run_command(GITS, ["describe", "--tags", "--dirty", "--always", "--long"], cwd=root) # --long was added in git-1.5.5 if describe_out is None: raise NotThisMethod("'git describe' failed") describe_out = describe_out.strip() full_out = run_command(GITS, ["rev-parse", "HEAD"], cwd=root) if full_out is None: raise NotThisMethod("'git rev-parse' failed") full_out = full_out.strip() pieces = {} pieces["long"] = full_out pieces["short"] = full_out[:7] # maybe improved later pieces["error"] = None # parse describe_out. It will be like TAG-NUM-gHEX[-dirty] or HEX[-dirty] # TAG might have hyphens. git_describe = describe_out # look for -dirty suffix dirty = git_describe.endswith("-dirty") pieces["dirty"] = dirty if dirty: git_describe = git_describe[:git_describe.rindex("-dirty")] # now we have TAG-NUM-gHEX or HEX if "-" in git_describe: # TAG-NUM-gHEX mo = re.search(r'^(.+)-(\d+)-g([0-9a-f]+)$', git_describe) if not mo: # unparseable. Maybe git-describe is misbehaving? pieces["error"] = ("unable to parse git-describe output: '%s'" % describe_out) return pieces # tag full_tag = mo.group(1) if not full_tag.startswith(tag_prefix): if verbose: fmt = "tag '%s' doesn't start with prefix '%s'" print(fmt % (full_tag, tag_prefix)) pieces["error"] = ("tag '%s' doesn't start with prefix '%s'" % (full_tag, tag_prefix)) return pieces pieces["closest-tag"] = full_tag[len(tag_prefix):] # distance: number of commits since tag pieces["distance"] = int(mo.group(2)) # commit: short hex revision ID pieces["short"] = mo.group(3) else: # HEX: no tags pieces["closest-tag"] = None count_out = run_command(GITS, ["rev-list", "HEAD", "--count"], cwd=root) pieces["distance"] = int(count_out) # total number of commits return pieces def do_vcs_install(manifest_in, versionfile_source, ipy): GITS = ["git"] if sys.platform == "win32": GITS = ["git.cmd", "git.exe"] files = [manifest_in, versionfile_source] if ipy: files.append(ipy) try: me = __file__ if me.endswith(".pyc") or me.endswith(".pyo"): me = os.path.splitext(me)[0] + ".py" versioneer_file = os.path.relpath(me) except NameError: versioneer_file = "versioneer.py" files.append(versioneer_file) present = False try: f = open(".gitattributes", "r") for line in f.readlines(): if line.strip().startswith(versionfile_source): if "export-subst" in line.strip().split()[1:]: present = True f.close() except EnvironmentError: pass if not present: f = open(".gitattributes", "a+") f.write("%s export-subst\n" % versionfile_source) f.close() files.append(".gitattributes") run_command(GITS, ["add", "--"] + files) def versions_from_parentdir(parentdir_prefix, root, verbose): # Source tarballs conventionally unpack into a directory that includes # both the project name and a version string. dirname = os.path.basename(root) if not dirname.startswith(parentdir_prefix): if verbose: print("guessing rootdir is '%s', but '%s' doesn't start with " "prefix '%s'" % (root, dirname, parentdir_prefix)) raise NotThisMethod("rootdir doesn't start with parentdir_prefix") return {"version": dirname[len(parentdir_prefix):], "full-revisionid": None, "dirty": False, "error": None} SHORT_VERSION_PY = """ # This file was generated by 'versioneer.py' (0.15) from # revision-control system data, or from the parent directory name of an # unpacked source archive. Distribution tarballs contain a pre-generated copy # of this file. import json import sys version_json = ''' %s ''' # END VERSION_JSON def get_versions(): return json.loads(version_json) """ def versions_from_file(filename): try: with open(filename) as f: contents = f.read() except EnvironmentError: raise NotThisMethod("unable to read _version.py") mo = re.search(r"version_json = '''\n(.*)''' # END VERSION_JSON", contents, re.M | re.S) if not mo: raise NotThisMethod("no version_json in _version.py") return json.loads(mo.group(1)) def write_to_version_file(filename, versions): os.unlink(filename) contents = json.dumps(versions, sort_keys=True, indent=1, separators=(",", ": ")) with open(filename, "w") as f: f.write(SHORT_VERSION_PY % contents) print("set %s to '%s'" % (filename, versions["version"])) def plus_or_dot(pieces): if "+" in pieces.get("closest-tag", ""): return "." return "+" def render_pep440(pieces): # now build up version string, with post-release "local version # identifier". Our goal: TAG[+DISTANCE.gHEX[.dirty]] . Note that if you # get a tagged build and then dirty it, you'll get TAG+0.gHEX.dirty # exceptions: # 1: no tags. git_describe was just HEX. 0+untagged.DISTANCE.gHEX[.dirty] if pieces["closest-tag"]: rendered = pieces["closest-tag"] if pieces["distance"] or pieces["dirty"]: rendered += plus_or_dot(pieces) rendered += "%d.g%s" % (pieces["distance"], pieces["short"]) if pieces["dirty"]: rendered += ".dirty" else: # exception #1 rendered = "0+untagged.%d.g%s" % (pieces["distance"], pieces["short"]) if pieces["dirty"]: rendered += ".dirty" return rendered def render_pep440_pre(pieces): # TAG[.post.devDISTANCE] . No -dirty # exceptions: # 1: no tags. 0.post.devDISTANCE if pieces["closest-tag"]: rendered = pieces["closest-tag"] if pieces["distance"]: rendered += ".post.dev%d" % pieces["distance"] else: # exception #1 rendered = "0.post.dev%d" % pieces["distance"] return rendered def render_pep440_post(pieces): # TAG[.postDISTANCE[.dev0]+gHEX] . The ".dev0" means dirty. Note that # .dev0 sorts backwards (a dirty tree will appear "older" than the # corresponding clean one), but you shouldn't be releasing software with # -dirty anyways. # exceptions: # 1: no tags. 0.postDISTANCE[.dev0] if pieces["closest-tag"]: rendered = pieces["closest-tag"] if pieces["distance"] or pieces["dirty"]: rendered += ".post%d" % pieces["distance"] if pieces["dirty"]: rendered += ".dev0" rendered += plus_or_dot(pieces) rendered += "g%s" % pieces["short"] else: # exception #1 rendered = "0.post%d" % pieces["distance"] if pieces["dirty"]: rendered += ".dev0" rendered += "+g%s" % pieces["short"] return rendered def render_pep440_old(pieces): # TAG[.postDISTANCE[.dev0]] . The ".dev0" means dirty. # exceptions: # 1: no tags. 0.postDISTANCE[.dev0] if pieces["closest-tag"]: rendered = pieces["closest-tag"] if pieces["distance"] or pieces["dirty"]: rendered += ".post%d" % pieces["distance"] if pieces["dirty"]: rendered += ".dev0" else: # exception #1 rendered = "0.post%d" % pieces["distance"] if pieces["dirty"]: rendered += ".dev0" return rendered def render_git_describe(pieces): # TAG[-DISTANCE-gHEX][-dirty], like 'git describe --tags --dirty # --always' # exceptions: # 1: no tags. HEX[-dirty] (note: no 'g' prefix) if pieces["closest-tag"]: rendered = pieces["closest-tag"] if pieces["distance"]: rendered += "-%d-g%s" % (pieces["distance"], pieces["short"]) else: # exception #1 rendered = pieces["short"] if pieces["dirty"]: rendered += "-dirty" return rendered def render_git_describe_long(pieces): # TAG-DISTANCE-gHEX[-dirty], like 'git describe --tags --dirty # --always -long'. The distance/hash is unconditional. # exceptions: # 1: no tags. HEX[-dirty] (note: no 'g' prefix) if pieces["closest-tag"]: rendered = pieces["closest-tag"] rendered += "-%d-g%s" % (pieces["distance"], pieces["short"]) else: # exception #1 rendered = pieces["short"] if pieces["dirty"]: rendered += "-dirty" return rendered def render(pieces, style): if pieces["error"]: return {"version": "unknown", "full-revisionid": pieces.get("long"), "dirty": None, "error": pieces["error"]} if not style or style == "default": style = "pep440" # the default if style == "pep440": rendered = render_pep440(pieces) elif style == "pep440-pre": rendered = render_pep440_pre(pieces) elif style == "pep440-post": rendered = render_pep440_post(pieces) elif style == "pep440-old": rendered = render_pep440_old(pieces) elif style == "git-describe": rendered = render_git_describe(pieces) elif style == "git-describe-long": rendered = render_git_describe_long(pieces) else: raise ValueError("unknown style '%s'" % style) return {"version": rendered, "full-revisionid": pieces["long"], "dirty": pieces["dirty"], "error": None} class VersioneerBadRootError(Exception): pass def get_versions(verbose=False): # returns dict with two keys: 'version' and 'full' if "versioneer" in sys.modules: # see the discussion in cmdclass.py:get_cmdclass() del sys.modules["versioneer"] root = get_root() cfg = get_config_from_root(root) assert cfg.VCS is not None, "please set [versioneer]VCS= in setup.cfg" handlers = HANDLERS.get(cfg.VCS) assert handlers, "unrecognized VCS '%s'" % cfg.VCS verbose = verbose or cfg.verbose assert cfg.versionfile_source is not None, \ "please set versioneer.versionfile_source" assert cfg.tag_prefix is not None, "please set versioneer.tag_prefix" versionfile_abs = os.path.join(root, cfg.versionfile_source) # extract version from first of: _version.py, VCS command (e.g. 'git # describe'), parentdir. This is meant to work for developers using a # source checkout, for users of a tarball created by 'setup.py sdist', # and for users of a tarball/zipball created by 'git archive' or github's # download-from-tag feature or the equivalent in other VCSes. get_keywords_f = handlers.get("get_keywords") from_keywords_f = handlers.get("keywords") if get_keywords_f and from_keywords_f: try: keywords = get_keywords_f(versionfile_abs) ver = from_keywords_f(keywords, cfg.tag_prefix, verbose) if verbose: print("got version from expanded keyword %s" % ver) return ver except NotThisMethod: pass try: ver = versions_from_file(versionfile_abs) if verbose: print("got version from file %s %s" % (versionfile_abs, ver)) return ver except NotThisMethod: pass from_vcs_f = handlers.get("pieces_from_vcs") if from_vcs_f: try: pieces = from_vcs_f(cfg.tag_prefix, root, verbose) ver = render(pieces, cfg.style) if verbose: print("got version from VCS %s" % ver) return ver except NotThisMethod: pass try: if cfg.parentdir_prefix: ver = versions_from_parentdir(cfg.parentdir_prefix, root, verbose) if verbose: print("got version from parentdir %s" % ver) return ver except NotThisMethod: pass if verbose: print("unable to compute version") return {"version": "0+unknown", "full-revisionid": None, "dirty": None, "error": "unable to compute version"} def get_version(): return get_versions()["version"] def get_cmdclass(): if "versioneer" in sys.modules: del sys.modules["versioneer"] # this fixes the "python setup.py develop" case (also 'install' and # 'easy_install .'), in which subdependencies of the main project are # built (using setup.py bdist_egg) in the same python process. Assume # a main project A and a dependency B, which use different versions # of Versioneer. A's setup.py imports A's Versioneer, leaving it in # sys.modules by the time B's setup.py is executed, causing B to run # with the wrong versioneer. Setuptools wraps the sub-dep builds in a # sandbox that restores sys.modules to it's pre-build state, so the # parent is protected against the child's "import versioneer". By # removing ourselves from sys.modules here, before the child build # happens, we protect the child from the parent's versioneer too. # Also see https://github.com/warner/python-versioneer/issues/52 cmds = {} # we add "version" to both distutils and setuptools from distutils.core import Command class cmd_version(Command): description = "report generated version string" user_options = [] boolean_options = [] def initialize_options(self): pass def finalize_options(self): pass def run(self): vers = get_versions(verbose=True) print("Version: %s" % vers["version"]) print(" full-revisionid: %s" % vers.get("full-revisionid")) print(" dirty: %s" % vers.get("dirty")) if vers["error"]: print(" error: %s" % vers["error"]) cmds["version"] = cmd_version # we override "build_py" in both distutils and setuptools # # most invocation pathways end up running build_py: # distutils/build -> build_py # distutils/install -> distutils/build ->.. # setuptools/bdist_wheel -> distutils/install ->.. # setuptools/bdist_egg -> distutils/install_lib -> build_py # setuptools/install -> bdist_egg ->.. # setuptools/develop -> ? from distutils.command.build_py import build_py as _build_py class cmd_build_py(_build_py): def run(self): root = get_root() cfg = get_config_from_root(root) versions = get_versions() _build_py.run(self) # now locate _version.py in the new build/ directory and replace # it with an updated value if cfg.versionfile_build: target_versionfile = os.path.join(self.build_lib, cfg.versionfile_build) print("UPDATING %s" % target_versionfile) write_to_version_file(target_versionfile, versions) cmds["build_py"] = cmd_build_py if "cx_Freeze" in sys.modules: # cx_freeze enabled? from cx_Freeze.dist import build_exe as _build_exe class cmd_build_exe(_build_exe): def run(self): root = get_root() cfg = get_config_from_root(root) versions = get_versions() target_versionfile = cfg.versionfile_source print("UPDATING %s" % target_versionfile) write_to_version_file(target_versionfile, versions) _build_exe.run(self) os.unlink(target_versionfile) with open(cfg.versionfile_source, "w") as f: LONG = LONG_VERSION_PY[cfg.VCS] f.write(LONG % {"DOLLAR": "$", "STYLE": cfg.style, "TAG_PREFIX": cfg.tag_prefix, "PARENTDIR_PREFIX": cfg.parentdir_prefix, "VERSIONFILE_SOURCE": cfg.versionfile_source, }) cmds["build_exe"] = cmd_build_exe del cmds["build_py"] # we override different "sdist" commands for both environments if "setuptools" in sys.modules: from setuptools.command.sdist import sdist as _sdist else: from distutils.command.sdist import sdist as _sdist class cmd_sdist(_sdist): def run(self): versions = get_versions() self._versioneer_generated_versions = versions # unless we update this, the command will keep using the old # version self.distribution.metadata.version = versions["version"] return _sdist.run(self) def make_release_tree(self, base_dir, files): root = get_root() cfg = get_config_from_root(root) _sdist.make_release_tree(self, base_dir, files) # now locate _version.py in the new base_dir directory # (remembering that it may be a hardlink) and replace it with an # updated value target_versionfile = os.path.join(base_dir, cfg.versionfile_source) print("UPDATING %s" % target_versionfile) write_to_version_file(target_versionfile, self._versioneer_generated_versions) cmds["sdist"] = cmd_sdist return cmds CONFIG_ERROR = """ setup.cfg is missing the necessary Versioneer configuration. You need a section like: [versioneer] VCS = git style = pep440 versionfile_source = src/myproject/_version.py versionfile_build = myproject/_version.py tag_prefix = "" parentdir_prefix = myproject- You will also need to edit your setup.py to use the results: import versioneer setup(version=versioneer.get_version(), cmdclass=versioneer.get_cmdclass(), ...) Please read the docstring in ./versioneer.py for configuration instructions, edit setup.cfg, and re-run the installer or 'python versioneer.py setup'. """ SAMPLE_CONFIG = """ # See the docstring in versioneer.py for instructions. Note that you must # re-run 'versioneer.py setup' after changing this section, and commit the # resulting files. [versioneer] #VCS = git #style = pep440 #versionfile_source = #versionfile_build = #tag_prefix = #parentdir_prefix = """ INIT_PY_SNIPPET = """ from ._version import get_versions __version__ = get_versions()['version'] del get_versions """ def do_setup(): root = get_root() try: cfg = get_config_from_root(root) except (EnvironmentError, configparser.NoSectionError, configparser.NoOptionError) as e: if isinstance(e, (EnvironmentError, configparser.NoSectionError)): print("Adding sample versioneer config to setup.cfg", file=sys.stderr) with open(os.path.join(root, "setup.cfg"), "a") as f: f.write(SAMPLE_CONFIG) print(CONFIG_ERROR, file=sys.stderr) return 1 print(" creating %s" % cfg.versionfile_source) with open(cfg.versionfile_source, "w") as f: LONG = LONG_VERSION_PY[cfg.VCS] f.write(LONG % {"DOLLAR": "$", "STYLE": cfg.style, "TAG_PREFIX": cfg.tag_prefix, "PARENTDIR_PREFIX": cfg.parentdir_prefix, "VERSIONFILE_SOURCE": cfg.versionfile_source, }) ipy = os.path.join(os.path.dirname(cfg.versionfile_source), "__init__.py") if os.path.exists(ipy): try: with open(ipy, "r") as f: old = f.read() except EnvironmentError: old = "" if INIT_PY_SNIPPET not in old: print(" appending to %s" % ipy) with open(ipy, "a") as f: f.write(INIT_PY_SNIPPET) else: print(" %s unmodified" % ipy) else: print(" %s doesn't exist, ok" % ipy) ipy = None # Make sure both the top-level "versioneer.py" and versionfile_source # (PKG/_version.py, used by runtime code) are in MANIFEST.in, so # they'll be copied into source distributions. Pip won't be able to # install the package without this. manifest_in = os.path.join(root, "MANIFEST.in") simple_includes = set() try: with open(manifest_in, "r") as f: for line in f: if line.startswith("include "): for include in line.split()[1:]: simple_includes.add(include) except EnvironmentError: pass # That doesn't cover everything MANIFEST.in can do # (http://docs.python.org/2/distutils/sourcedist.html#commands), so # it might give some false negatives. Appending redundant 'include' # lines is safe, though. if "versioneer.py" not in simple_includes: print(" appending 'versioneer.py' to MANIFEST.in") with open(manifest_in, "a") as f: f.write("include versioneer.py\n") else: print(" 'versioneer.py' already in MANIFEST.in") if cfg.versionfile_source not in simple_includes: print(" appending versionfile_source ('%s') to MANIFEST.in" % cfg.versionfile_source) with open(manifest_in, "a") as f: f.write("include %s\n" % cfg.versionfile_source) else: print(" versionfile_source already in MANIFEST.in") # Make VCS-specific changes. For git, this means creating/changing # .gitattributes to mark _version.py for export-time keyword # substitution. do_vcs_install(manifest_in, cfg.versionfile_source, ipy) return 0 def scan_setup_py(): found = set() setters = False errors = 0 with open("setup.py", "r") as f: for line in f.readlines(): if "import versioneer" in line: found.add("import") if "versioneer.get_cmdclass()" in line: found.add("cmdclass") if "versioneer.get_version()" in line: found.add("get_version") if "versioneer.VCS" in line: setters = True if "versioneer.versionfile_source" in line: setters = True if len(found) != 3: print("") print("Your setup.py appears to be missing some important items") print("(but I might be wrong). Please make sure it has something") print("roughly like the following:") print("") print(" import versioneer") print(" setup( version=versioneer.get_version(),") print(" cmdclass=versioneer.get_cmdclass(), ...)") print("") errors += 1 if setters: print("You should remove lines like 'versioneer.VCS = ' and") print("'versioneer.versionfile_source = ' . This configuration") print("now lives in setup.cfg, and should be removed from setup.py") print("") errors += 1 return errors if __name__ == "__main__": cmd = sys.argv[1] if cmd == "setup": errors = do_setup() errors += scan_setup_py() if errors: sys.exit(1) pg8000-1.10.6/README.creole0000664000175000017500000000571212721143017015436 0ustar tlocketlocke00000000000000=pg8000 pg8000 is a pure-[[http://www.python.org/|Python]] [[http://www.postgresql.org/|PostgreSQL]] driver that complies with [[http://www.python.org/dev/peps/pep-0249/|DB-API 2.0]]. The driver communicates with the database using the [[http://www.postgresql.org/docs/current/static/protocol.html|PostgreSQL Frontend/Backend Protocol]]. CircleCI [[https://circleci.com/gh/mfenniak/pg8000|Build Status]]: {{https://circleci.com/gh/mfenniak/pg8000.png?style=badge|CircleCI}} Links: * [[http://pythonhosted.org/pg8000/|User Docs]] * [[https://groups.google.com/forum/#!forum/pg8000|Forum]] * [[https://github.com/mfenniak/pg8000|Code, bugs, feature requests etc.]] =Regression Tests To run the regression tests, install [[http://testrun.org/tox/latest/|tox]]: {{{ pip install tox }}} then install all the supported Python versions (using the [[https://launchpad.net/~fkrull/+archive/ubuntu/deadsnakes|APT Repository]] if you're using Ubuntu). Install all the currently supported versions of PostgreSQL (using the [[http://wiki.postgresql.org/wiki/Apt|APT Repository]] if you're using Ubuntu). Then for each of them, enable the hstore extension by running the SQL command: {{{ create extension hstore; }}} and add a line to pg_hba.conf for the various authentication options, eg. {{{ host pg8000_md5 all 127.0.0.1/32 md5 host pg8000_gss all 127.0.0.1/32 gss host pg8000_password all 127.0.0.1/32 password host all all 127.0.0.1/32 trust }}} Set the following environment variables for the databases, for example: {{{ export PG8000_TEST_NAME="PG8000_TEST_9_5" export PG8000_TEST_9_1="{'user': 'postgres', 'password': 'pw', 'port': 5435}" export PG8000_TEST_9_2="{'user': 'postgres', 'password': 'pw', 'port': 5434}" export PG8000_TEST_9_3="{'user': 'postgres', 'password': 'pw', 'port': 5433}" export PG8000_TEST_9_4="{'user': 'postgres', 'password': 'pw', 'port': 5432}" export PG8000_TEST_9_5="{'user': 'postgres', 'password': 'pw', 'port': 5431}" }}} then run {{{tox}}} from the {{{pg8000}}} directory: {{{ tox }}} ==Performance Tests To run the performance tests from the {{{pg8000}}} directory: {{{ python -m pg8000.tests.performance }}} ==Stress Test There's a stress test that is run by doing: {{{ python ./multi }}} The idea is to set {{{shared_buffers}}} in postgresql.conf to 128kB, and then run the stress test, and you should get {{{no unpinned buffers}}} errors. =Building The Documentation The docs are written using [[http://sphinx-doc.org/|Sphinx]]. To build them, install sphinx: {{{ pip install sphinx }}} Then type: {{{ python setup.py build_sphinx }}} and the docs will appear in {{{build/sphinx/html}}}. =Doing A Release Of pg8000 Run {{{tox}}} to make sure all tests pass, then update {{{doc/release_notes.rst}}} then do: {{{ git tag -a x.y.z -m "version x.y.z" python setup.py register sdist bdist_wheel upload build_sphinx upload_docs }}} pg8000-1.10.6/setup.cfg0000664000175000017500000000044512726514145015136 0ustar tlocketlocke00000000000000[upload_docs] upload-dir = build/sphinx/html [bdist_wheel] universal = 1 [versioneer] vcs = git style = pep440 versionfile_source = pg8000/_version.py versionfile_build = pg8000/_version.py tag_prefix = parentdir_prefix = pg8000- [egg_info] tag_build = tag_date = 0 tag_svn_revision = 0