Common utilies for Django used at TrackMaven

Docs are avaible here.

Installation

$ pip install trackmaven-django --extra-index-url https://pypi.fury.io/trackmaven/

If you want to include this on a requirements.txt, use the following syntax...

<other packages>
--extra-index-url https://pypi.fury.io/trackmaven/
trackmaven-django==1.0.0

Development

Inside of a virtualenv, to install the required packages, run

pip install -e .
pip install -r requirements-dev.txt

Or simply run

make setup

This project uses py.test as its test runner. To run the tests

make tests

or you can call py.test directly with...

py.test -vv

To run the test suite against all support Python versions (2.7 and 3.4) run...

tox

Docs

Documentation is generated by Sphinx. If you are unfamiliar with it, check out this handy cheatsheet.

To build the docs, run

make build-docs

To see the docs, after building, run

make serve-docs

Release Checklist

  • Bump version in trackmaven_common/__init__.py
  • Add changes to CHANGELOG.rst
  • Open PR with title “Release <version>”
  • Build + push dist to gemfury.
python setup.py sdist
curl -F package=@<file> https://<gemfury_token>@push.fury.io/trackmaven/

API

models Module

The models modules holds a bunch of useful base abstract models meant to be drop in replacements for django.db.models

  • models
class trackmaven_django.models.BaseModel(*args, **kwargs)

Bases: django.db.models.base.Model

Abstract model for models that require validation before saving.

Example:

from trackmaven_django.models import BaseModel

class Post(BaseModel):
    text = models.TextField()
    ...
class Meta
abstract = False
BaseModel.save(*args, **kwargs)

Tries to clean the model and its fields before saving to avoid database errors that might occur from forcing a field to something that doesn’t follow the DB schema e.g. a string too long for a field.

class trackmaven_django.models.ChangedModel(*args, **kwargs)

Bases: trackmaven_django.models.ChangedModelMixin, trackmaven_django.models.BaseModel

Abstract model that combines BaseModel + ChangedModelMixin. Includes pre-save validation + ability to see changes on a model.

Example:

from trackmaven_django.models import ChangedModel

class Post(ChangedModel):
    text = models.TextField()
    ...
class Meta
abstract = False
class trackmaven_django.models.ChangedModelMixin(*args, **kwargs)

Bases: object

A model mixin that tracks model fields’ values and provide some useful tools to know what fields have been changed.

Example:

>>> c = Company()
>>> c.has_changed
False
>>> c.changed_fields
[]
>>> c.name = "Nike"
>>> c.has_changed
True
>>> c.changed_fields
['name']
>>> c.diff
{'name': (None, 'Nike')}
changed_fields

Returns a list of the changed fields.

Example:

>>> p = Post.objects.get(pk=1)
>>> p.changed_fields
[]
>>> p.url = "http://trackmaven.com"
>>> p.changed_fields
["url"]
diff

Returns a dictionary of all fields whose values have changed and for each a tuple of the original vs new field values.

Example:

>>> p = Post()
>>> p.diff
{}
>>> p.url = "http://trackmaven.com"
>>> p.diff
{
    'url': (None, "http://trackmaven.com")
}
has_changed

Returns a boolean indicating if the model’s field values have changed.

Example:

>>> p = Post.objects.get(pk=1)
>>> p.has_changed
False
>>> p.url = "http://trackmaven.com"
>>> p.has_changed
True
save(*args, **kwargs)

Saves model and set initial state.

to_dict

Transform the model into a dictionary.

Example:

>>> p = Post(url="http://trackmaven.com", title="Hello")
>>> p.to_dict
{"url": "http://trackmaven.com", "title": "Hello"}

query Module

The query holds querying utilities.

  • query
trackmaven_django.query.get_object_or_make(klass, *args, **kwargs)

The long lost sibling of Django’s get_or_create.

Attempts to look for and get a model, if none is found, just populates the model class with the look up fields.

Example:

>>> instance, exists = get_object_or_make(Post, url="http://trackmaven.com")
>>> instance.pk
1
>>> exists
True

Returns:

object: The django model passed in exists (boolean): An boolean specifying whether an object was found.

Changelog

<YYYY-MM-DD>

<Short description of what has changed>

  • <List of changes>
  • <One by one>