Tools and such for handling development of Armstrong applications
This package contains some of the various helpers needed to do development work on the Armstrong packages. If you're not actively developing, or working with development versions of Armstrong, you probably don't need this package.
Installation & Configuration
If you are just running tests for a component, Tox will grab everything it needs including ArmDev.
pip install toxand run
pip install armstrong.dev invoke
Invoke is not strictly required. ArmDev is as lean as possible to support fast virtualenv creation so multi-environment testing tools like TravisCI and Tox will complete ASAP.
Many of the Invoke tasks have their own package requirements and they will nicely notify you if something they require needs to be installed.
This component supports Django 1.3, 1.4, 1.5, 1.6, 1.7 on Python 2.6 and 2.7.
Most Armstrong components already have the necessary configuration to use these
Dev tools. Specifically, components need
files. Assuming these are present:
- to see a list of all available commands
invoke --help <cmd>
- for help on a specific command
Several of the tasks take an optional
--extra argument that is used as a
catch-all way of passing arbitrary arguments to the underlying command. Invoke
cannot handle arbitrary args (like Fabric 1.x could) so this is our workaround.
Two general rules: 1) enclose multiple args in quotes 2) kwargs need to use
"=" with no spaces (our limitation, not Invoke's). Example:
invoke test --extra "--verbosity=2 <path.to.app.test1> <path.to.app.test2>"
invoke install [--editable]
- to "pip install" the component, by default as an editable install. For
a regular install, use
invoke test [--extra ...]
- to run tests where --extra handles anything the normal Django "manage.py test" command accepts.
invoke coverage [--reportdir=<directory>] [--extra ...]
- for running test coverage. --extra works the same as in "invoke test" passing
arbitrary args to the underlying test command. --reportdir is where the HTML
report will be created; by default this directory is named "htmlcov" or
whatever is set in the
invoke managepy <cmd> [--extra ...]
- to run any Django "manage.py" command where --extra handles any arbitrary
invoke managepy shellor
invoke managepy runserver --extra 9001
invoke create_migration [--initial]
- to create a South migration for the component (in Django <1.7). An "auto" migration is default if the --initial flag is not used.
There are other commands as well, but these are the most useful. Remember
that individual components may provide additional Invoke tasks as well. So
invoke --list to discover them all.
If you are creating a new Armstrong component or updating one that uses the pre-2.0 ArmDev, you'll need to create (or port to) these two files:
tasks.pyand add the following:
from armstrong.dev.tasks import * # any additional Invoke commands # ...
env_settings.pyand add the following:
from armstrong.dev.default_settings import * # any additional settings # it's likely you'll need to extend the list of INSTALLED_APPS # ...
Not required but as long as you are reviewing the general state of things, take care of these too!
Review the TravisCI configuration
Drop Lettuce tests and requirements
Review the README text and setup.py metadata
Use Setuptools and fix any improper namespacing
Stop shipping tests by moving tests/ to the root directory
If the component uses logging, consider namespacing it with
logger = logging.getLogger(__name__).
CHANGES.rstfile and include it in the MANIFEST
.gitignore. You might want to ignore these:
.tox/ coverage*/ *.egg-info
Notable changes in 2.0
Setuptools is now explicitly used/required instead of Distutils.
Invoke replaces Fabric for a leaner install without the SSH and crypto stuff. Invoke is still pre-1.0 release so we might have some adjustment to do later.
This version offers an easier and more standard way to run a Django environment with a component's specific settings, either from the commandline or via import.
It provides an "a la carte" requirements approach. Meaning that if you run an Invoke command that needs a package that isn't installed, it will prompt you to install it instead of requiring everything up-front. This allows for much faster virtualenv creation (which saves considerable time in testing) and doesn't pollute your virtualenv with packages for features you don't use.
coverage will work better with automated test tools like
TravisCI and Tox. These commands also now work like Django's native test
command so that you can pass arguments for running selective tests or
changing the output verbosity.
Settings are now defined in the normal Django style in an
file instead of as a dict within the tasks file. It's not called "settings.py"
to make it clearer that these are settings for the development and testing
of this component, not necessarily values to copy/paste for incorporating
the component into other projects.
The full list of changes and backward incompatibilties is available in CHANGES.rst.
Development occurs on Github. Participation is welcome!
- Found a bug? File it on Github Issues. Include as much detail as you can and make sure to list the specific component since we use a centralized, project-wide issue tracker.
- Have code to submit? Fork the repo, consolidate your changes on a topic branch and create a pull request.
- Questions, need help, discussion? Use our Google Group mailing list.
State of Project
Armstrong is an open-source news platform that is freely available to any organization. It is the result of a collaboration between the Texas Tribune and The Center for Investigative Reporting and a grant from the John S. and James L. Knight Foundation. Armstrong is available as a complete bundle and as individual, stand-alone components.