atelier.fablib

(source code)

This module is a library for fabric with tasks I use to manage my Python projects.

To be used by creating a fabfile.py in your project’s root directory with at least the following two lines:

from atelier.fablib import *
setup_from_project("foobar")

Where “foobar” is the Python name of your project’s main package.

Configuration files

fabfile.py

In your fabfile.py file you can specify project-specific configuration settings. Example content:

from atelier.fablib import *
setup_from_project("foobar")
env.languages = "de fr et nl".split()
env.tolerate_sphinx_warnings = True
add_demo_database('foobar.demo.settings')
.fabricrc

To specify certain default preferences for all your projects, you can create a file named .fabricrc in your home directory with content like this:

user = luc
blogger_project = lino
docs_rsync_dest = luc@example.org:~/public_html/%s
sdist_dir = /home/luc/projects/lino/docs/dl
temp_dir = /home/luc/tmp

Project settings

fabric works with a global “environment” object named env. The following section documents the possible attributes of this object as used by atelier.fablib.

class atelier.fablib.env
doc_trees

Replaced by doc_trees attribute of the project’s main module.

A list of directory names (relative to your project directory) containing Sphinx document trees. Default value is ['docs']

tolerate_sphinx_warnings

Whether sphinx-build html should tolerate warnings.

languages

A list of language codes for which userdocs are being maintained.

apidoc_exclude_pathnames

a list of filenames (or directory names) to be excluded when you run fab api.

use_mercurial

set this to False if you use Git. Used by fab ci

demo_databases

You may define user-specific default values for some of these settings (those who are simple strings) in a .fabricrc file.

fab commands

fab mm

(“make messages”)

Extracts messages from both code and userdocs, then initializes and updates all catalogs.

fab test

Run the test suite of this project.

fab test_sdist

Creates a temporay virtualenv, installs your project and runs your test suite.

  • creates and activates a temporay virtualenv,
  • calls pip install --extra-index <env.sdist_dir> <prjname>
  • runs python setup.py test
  • removes temporary files.

Assumes that you previously did pp fab sdist i.e. your env.sdist_dir contains the pre-release sdist of all your projects.

When using this, you should configure a local download cache for pip, e.g. with something like this in your ~/.pip/pip.conf:

[global]
download-cache=/home/luc/.pip/cache
fab initdb

Run initdb_demo on every demo database of this project (specified in env.demo_databases).

Demo databases are used by the test suite and the Sphinx documentation. They are not included in the code repository since they are generated data. Since initializing these databases can take some time, this is not automatically launched for each test run.

fab ci

Checkin and push to repository, using today’s blog entry as commit message.

fab clean

Remove temporary and generated files:

  • .pyc files which don’t have a corresponding .py file.
  • Sphinx .build files
  • cache of demo databases
fab release

Create official source distribution and upload it to PyPI.

PyPI will refuse if this project has previously been released with the same version.

fab write_readme

Generate README.txt file from project_info (if necessary).

fab api

Generate .rst files below docs/api by running sphinx-apidoc.

fab blog

Edit today’s blog entry, create an empty file if it doesn’t yet exist.

fab docs

Run sphinx build html in every directory defined in doc_trees.

History

  • 20141020 moved doc_trees project to atelier.Project.
  • 20141001 added support for multiple doc trees per project (env.doc_trees).
  • 20140116 : added support for managing namespace packages

TODO

  • replace env.blogger_project by an attribute of the main module (like intersphinx_urls)

Functions

abort(msg) Abort execution, print msg to stderr and exit with error status (1.)
add_demo_database(db)
clean_demo_caches()
cleanup_pyc(p) Thanks to oddthinking on http://stackoverflow.com/questions/2528283
confirm(question[, default]) Ask user a yes/no question and return their response as True or False.
extract_messages() Extract messages from source files to django.pot file
extract_messages_userdocs() Run the Sphinx gettext builder on userdocs.
format_date([date, format, locale]) Return a date formatted according to the given pattern.
get_blog_entry(today) Return an RstFile object representing the blog entry for that date in the current project.
get_current_date() Useful when a working day lasted longer than midnight, or when you start some work in the evening, knowing that you won’t commit it before the next morning.
get_doc_trees()
get_locale_dir()
i2d(i) Convert int to date.
init_catalog_code() Create code .po files if necessary.
lcd(path) Context manager for updating local current working directory.
local(command[, capture, shell]) Run a command on the local system.
must_confirm(*args, **kw)
must_exist(p)
publish_docs(build_dir, dest_url)
puts(text[, show_prefix, end, flush]) An alias for print whose output is managed by Fabric’s output controls.
py_clean() Delete dangling .pyc files.
rmtree_after_confirm(p)
run_in_demo_databases(admin_cmd, *more) Run the given django admin command for each demo database.
setup_babel_userdocs(babelcmd) Create userdocs .po files if necessary.
setup_from_project([main_package, ...])
sphinx_build(builder, docs_dir[, ...])
sphinx_clean() Delete all generated Sphinx files.
sync_docs_data(docs_dir)
task(*args, **kwargs) Decorator declaring the wrapped function to be a new-style task.
unused_write_release_notes() Generate docs/releases/x.y.z.rst file from setup_info.
update_catalog_code() Update .po files from .pot file.

Classes

JarBuilder(jarfile, sourcedir) Used by my Java projects davlink and eidreader.
Path
RstFile(local_root, url_root, parts)