{ "info": { "author": "Jesse Heitler", "author_email": "jesseh@i-iterate.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 3 - Alpha", "Environment :: Web Environment", "Framework :: Django", "Intended Audience :: Developers", "Operating System :: OS Independent", "Programming Language :: Python" ], "description": "==================\ndjango-stockandflow\n==================\n\nDjango stock and flow tracking for business intelligence\n\nInstallation\n============\n\n1. Install from PyPI with ``pip``::\n\n pip install django-stockandflow\n\n.. _in-development version: https://github.com/jesseh/django-stockandflow.git\n\n2. Add ``stockandflow`` to ``INSTALLED_APPS`` setting.\n\n3. Create a cron job to call ``./manage.py run_periodic_schedule`` at an\n interval that is at least as frequent as your most frequent period that you\n register with the periodic scheduler. Hourly, or perhaps every 10 minutes,\n is likely to be sufficient.\n\n4. Start creating stocks and flows.\n\nDependencies\n------------\n\n- ``Django >= 1.2`` (not yet tested with 1.3)\n\n.. _Django: http://www.djangoproject.com/\n\nIntroduction\n============\n\nDjango Stock and Flow is a business intelligence tool. The goal is to transform\nthe raw data in a Django application into views that answer business questions.\nJust as the Django Admin interface makes it easy to manage data in your\nproject, Django Stock and Flow makes it easy to define, track and present\nbusiness metrics for your project.\n\nThe theory behind Django Stock and Flow is based on `system dynamics`_. There\nis more information on the concept of stocks and flows on wikipedia_.\n\nIn addition to tracking metrics, Django Stock and Flow has hooks for running\nautomation code when flow events occur and when the stocks are counted. These\nhooks are useful, for example, to create decaying stocks. The system can\nautomatically transition an object through a set of states, like 'hot', 'warm'\nand 'cold' over time.\n\n**This app is very much in development.** The api is likely to change in ways\nthat are not backwards compatible.\n\n.. _`system dynamics`: http://en.wikipedia.org/wiki/System_dynamics\n.. _wikipedia: http://en.wikipedia.org/wiki/Stock_and_flow\n\nKey Concepts\n============\n\nStock\n-----\nAn accumulation defined by a queryset. \n\nIn the abstract a stock is a collection that is counted at a specific time\ninterval, generating a StockRecord). The state of an object defines it's\nmembership in a given stock. As a result, the words state and stock are roughly\ninterchangeable.\n\nIn the specific a stock is a subset of records for a given model that meet the\nconditions defined in the queryset.\n\nFor example a User may have an \"active\" stock and an \"inactive\" stock defined\nby whether or not each user.is_active == True.\n\nThere is no model associated with a stock.\n\nFacets is a list of either facet objects or tuples of the form (facet,\nfield_prefix). The field prefix maps the object of the stock to the object that\nis filtered in the facet. For example, if there is a User with a Profile and a\nfacet on the Profile object like \"yada\"=\"true\" then a User stock would use the\nfield_prefix \"profile\" so that the field lookup in the facet becomes\n\"profile__yada\"=True.\n\n\nFlow\n----\nA named relationship between stocks representing the transition of an object\nfrom a source stock to a sink stock. A flow enables the transitions to measured\nover an interval of time to track the rate of occurence.\n\nA flow may have any number of source or sinks stocks. None is a valid source or\nsink that represents an external, or untracked stock. Any other class, such as\nan int or a string can be used a stock stand-in for creating flow events\nbetween states that do not have an associated Stock instance.\n\nContinuing the example in the Stock docstring, when a new user is created the\nflow from None to the stock \"active\". A flow to track this tranisition could be\ncalled \"activating\". The activating flow would also have \"inactive\" as a\nsource to handle the case where a previously inactive user becomes active\nagain.\n\nThe optional event_callables list is called whenever an flow event is created\nfor this flow. It receives the flowed_obj, source and sink. An example use\nwould be to send an email each time an activating flow occurs.\n\n\nFacet\n-----\nA facet is used to split a stock or flow into sub-queries. For example, one\ncould track users, and then add a facet based on is_active to track how many\nare active vs. inactive.\n\n - The name is used to refer to the facet.\n - The field lookup is the same as the left side of a kwarg in a filter\n function.\n - Values can either be a list or a ValuesQuerySet with flat=True. If it is a\n ValuesQuerySet then it will be re-evaluated at every use.\n \n\nFlow Event\n----------\nAn abstract base class for the timestamped event of an object moving from one\nstock to another.\n\nEach type of object that flows needs to have an subclass of the FlowEvent model\nto capture events on objects of that class. This approach avoids using a\ngeneric foreign key and the limitations that come with it.\n\nFlow events combine to create a flow variable that is measured over an\ninterval of time. Therefore a flow would be measured per unit of time (say a\nyear).\n\nSubclasses must have a \"subject\" foreign key field.\n\n\nStock Record and Stock Facet Record\n------------\nA record of the count of a given stock and its facets at a point in time. There\nis one model to capture the stock records for all the stocks.\n\n\nFlow Record and Flow Facet Record\n------------\n*To be implemnted*\n\nA record of the time-framed count of flow events for a given flow and its\nfacets. There is one model to capture the flow event records for all the flows.\n\n\nModel Tracker\n-------------\nA common use case is to generate flow events when data in a given model\nchanges. This class does the heavy lifting to make that happen.\n\nIt generates flow events by monitoring for changes to the fields_to_track\nlist, runs the old and new field values through the states_to_stocks_func\nfunction to figure out the source and sink stocks. Then it tries to checks\nif any of the flows will make an event for that transition.\n\nThe states_to_stocks_func receives two tuples of field values in the order that\nthey are declared in fields_to_track. The first tuple lists the previous value of the\nfields and the second tuple lists the current value of the fields. The function must\nreturn a pair of tuples of stocks (they can be a 1-tuple). This allows a single model's\nstate be composed of any number of sub-states/stocks. The resulting previous\nand current state tuples are then compared element by element.\n\nThanks to carljm for the monitor in django-model-utils on which the\nchange tracking is based.\n\n\nPeriodic Scheduler\n------------------\nPeriodically call a set of registered callable functions.\n\nThis can be used, for example, to periodically count a stock and generate stock\nrecords. It could also be used to periodically decay objects from one stock to\nanother.\n\nThe periodic scheduler requires that a cron job call the management command\n``run_periodic_schedule`` at regular intervals. The system sorts out which\nregistered function to run at each invocation.\n\n\nProcess\n-------\n\nA view helper class to group stocks for use in a view. Any set of stocks, flows\nand associated facets can be added to a Process. Passing the Process object to\na template is an easy way to provide all of the data required for a given set\nof metrics.\n\n*The Process class is only a skeleton implementation. In the future it should\ninclude helpers and possibly templates to rapdily report on stocks and flows.*\n\n\nStock and Flow Admin\n--------------------\nThis leverages Django's fantastic built-in admin to offer great functionality\nfor both stocks and flows. Via this interface the stocks and flows can be\nviewed and actions applied.\n\nThe StockAndFlowAdminSite registers a proxy model for each stock and flow to\nget around the fact that the admin site does not like a given model to be\nregistered more than once.\n\nThis stock and flow admin is meant to be registered as a seperate admin site so\nthat it does not clutter up the normal admin with dynamically created stock and\nflow entries.\n\n\nUsage\n=====\nSee the ``example`` folder. This code is meant to be an example. **It will not\nexecute.**\n\n\nFor Help\n========\nDjango Stock and Flow is very much in development and the documentation could\nuse some work. If you want help implementing this please contact me at\njesseh@i-iterate.com.\n\nCHANGES\n=======\n\ntip (unreleased)\n----------------\n\n0.0.1 (2011.06.30)\n------------------\n- Initial release\n\n0.0.2-4 (2011.12.3)\n------------------\n- Fixed pip install process.\nTODO\n====\n\n- Create FlowRecords.\n- Enhance views to generate generic stock and flow reports for a process.\n- Test with Django 1.3.", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "http://github.com/jesseh/django-stockandflow/", "keywords": null, "license": "LICENSE.txt", "maintainer": null, "maintainer_email": null, "name": "django-stockandflow", "package_url": "https://pypi.org/project/django-stockandflow/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/django-stockandflow/", "project_urls": { "Download": "UNKNOWN", "Homepage": "http://github.com/jesseh/django-stockandflow/" }, "release_url": "https://pypi.org/project/django-stockandflow/0.0.4/", "requires_dist": null, "requires_python": null, "summary": "Django stock and flow tracking for business intelligence metrics", "version": "0.0.4" }, "last_serial": 790774, "releases": { "0.0.1": [ { "comment_text": "", "digests": { "md5": "675e733bf95f64d145bcea16fab5925d", "sha256": "740a58bbd56f70332771ee0146953959c61df12fc228421894e5f39df521adf8" }, "downloads": -1, "filename": "django-stockandflow-0.0.1.tar.gz", "has_sig": false, "md5_digest": "675e733bf95f64d145bcea16fab5925d", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 18965, "upload_time": "2011-06-30T22:24:33", "url": "https://files.pythonhosted.org/packages/4d/92/facc1af231a31d3129a8671b133a2180a146120746820179a5311560db53/django-stockandflow-0.0.1.tar.gz" } ], "0.0.2": [ { "comment_text": "", "digests": { "md5": "9dad34e21b4f26042ca8ae5b5f7d6c0d", "sha256": "a9113e767ab55a11077f154d2fab211126f30c0a3c03803f9ab5c065cd8019a3" }, "downloads": -1, "filename": "django-stockandflow-0.0.2.tar.gz", "has_sig": false, "md5_digest": "9dad34e21b4f26042ca8ae5b5f7d6c0d", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 22180, "upload_time": "2011-12-03T22:22:45", "url": "https://files.pythonhosted.org/packages/be/b1/664df83c5418b24c822faf2379db6da63facf9c7f041f0787cfd49fb382a/django-stockandflow-0.0.2.tar.gz" } ], "0.0.3": [ { "comment_text": "", "digests": { "md5": "75d3566d72d1494fc4639b72fe276b4a", "sha256": "624c0f636670786279008c1eed79f4c84b1d460ddcd41b35412cc0b002bb7b08" }, "downloads": -1, "filename": "django-stockandflow-0.0.3.tar.gz", "has_sig": false, "md5_digest": "75d3566d72d1494fc4639b72fe276b4a", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 22218, "upload_time": "2011-12-03T22:30:51", "url": "https://files.pythonhosted.org/packages/85/f2/efd64c50679a0b21e6d5a55b381154d40e3f413e911d229cbe8b77bb990a/django-stockandflow-0.0.3.tar.gz" } ], "0.0.4": [ { "comment_text": "", "digests": { "md5": "9b4c23f8086618bdd86883cbf5a528da", "sha256": "44d03d7d14f9181838dd6a171c477c0c1369845da72f120eb42625eb77b53ccb" }, "downloads": -1, "filename": "django-stockandflow-0.0.4.tar.gz", "has_sig": false, "md5_digest": "9b4c23f8086618bdd86883cbf5a528da", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 23067, "upload_time": "2011-12-03T22:41:43", "url": "https://files.pythonhosted.org/packages/d6/f5/635b9e86625b4ab6def220d620548b904822b22818fa110c5d5a7b0fddef/django-stockandflow-0.0.4.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "9b4c23f8086618bdd86883cbf5a528da", "sha256": "44d03d7d14f9181838dd6a171c477c0c1369845da72f120eb42625eb77b53ccb" }, "downloads": -1, "filename": "django-stockandflow-0.0.4.tar.gz", "has_sig": false, "md5_digest": "9b4c23f8086618bdd86883cbf5a528da", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 23067, "upload_time": "2011-12-03T22:41:43", "url": "https://files.pythonhosted.org/packages/d6/f5/635b9e86625b4ab6def220d620548b904822b22818fa110c5d5a7b0fddef/django-stockandflow-0.0.4.tar.gz" } ] }