Skip to main content

Autodoc extension to pretty print canned SA queries

Project description

author:

Lele Gaifax

contact:

lele@metapensiero.it

license:

GNU General Public License version 3 or later

This is a very simple extension to Sphinx that injects the ability to recognize and pretty print SQLAlchemy statements into its automodule and autoclass directives.

To use it, first of all you must register the extension within the Sphinx environment, adding the full name of the package to the extensions list in the file conf.py, for example:

# Add any Sphinx extension module names here, as strings.
extensions = ['metapensiero.sphinx.autodoc_sa']

Without further settings it uses the default SQLAlchemy stringification strategy, but you can explicitly choose the right dialect by setting autodoc_sa_dialect to a string containing its fully qualified name, for example:

autodoc_sa_dialect = 'sqlalchemy.dialects.postgresql.dialect'

Otherwise, you can set it using the -D option of the sphinx-build command, e.g. adding -D autodoc_sa_dialect=my.own.dialect to the SPHINXOPTS of the Makefile created by sphinx-quickstart.

At this point, any documented SQLAlchemy core statement or ORM query, appearing either at the module level or as a class attribute, will be compiled into SQL, beautified using sqlparse.format() and added to the documentation wrapped within a code-block:: sql directive.

If you chose a specific SQLAlchemy dialect, by any chance you may want to select the right Pygments lexer to adjust the highlighting rules, instead of the default sql:

autodoc_sa_pygments_lang = 'postgresql'

If you are using PostgreSQL, you may prefer using the pglast SQL prettifier over the default one based on sqlparse:

autodoc_sa_prettifier = 'pglast'

Changes

2.1 (2019-03-31)

  • Minor tweak for compatibility with recently released Sphinx 2.0

2.0 (2018-06-16)

1.7 (2018-05-24)

  • Avoid prettification of BindParameters

1.6 (2018-05-23)

  • Use Sphinx 1.7+ API to install the extension

1.5 (2017-08-10)

  • New option autodoc_sa_prettifier_options to pass arbitrary keyword options to the prettifier function

1.4 (2017-08-09)

  • Replace the dynamic argument placeholders injected by SA with their literal values, leaving the developer’s explicit bindparams alone

1.3 (2017-08-08)

  • Handle also the pglast SQL prettifier

  • New options, autodoc_sa_prettifier and autodoc_pygments_lang

1.2 (2017-03-22)

  • Minor tweak, no externally visible changes

1.1 (2017-01-17)

  • First release on PyPI

1.0 (unreleased)

  • Polished, tested and extended to support class’ attributes as well

  • Extracted from metapensiero.sphinx.patchdb

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

metapensiero.sphinx.autodoc_sa-2.1.tar.gz (9.6 kB view details)

Uploaded Source

File details

Details for the file metapensiero.sphinx.autodoc_sa-2.1.tar.gz.

File metadata

  • Download URL: metapensiero.sphinx.autodoc_sa-2.1.tar.gz
  • Upload date:
  • Size: 9.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.21.0 setuptools/40.6.2 requests-toolbelt/0.9.1 tqdm/4.31.1 CPython/3.7.3

File hashes

Hashes for metapensiero.sphinx.autodoc_sa-2.1.tar.gz
Algorithm Hash digest
SHA256 d4429a394ffe239b5f276d1bb0c8080a0b8f6d774819fb1e230318b31298d2fc
MD5 08729eba9e858f065f87f461bf44ba46
BLAKE2b-256 c298cb64f463f30fd387e68c60926847296f8c53e074fdbc45e4fa8bec15b57c

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page