django-cratis Documentation

(1)

django-cratis Documentation

Release 0.4.2

Alex Rudakov

June 12, 2014

(2)

(3)

Contents

1 Development status & project plans 1

1.1 Code quality . . . 1

1.2 History . . . 1

1.3 Plans . . . 1

2 Getting Started 3 2.1 Installation . . . 3

2.2 Running cratis . . . 3

2.3 Understanding structure . . . 3

2.4 Creating own Feature. . . 5

3 Licencing 7 3.1 Comments . . . 7

3.2 Simlified BSD Licence. . . 7

4 Api Detailed documentation 9 4.1 Feature API. . . 9

4.2 Settings API . . . 10

4.3 CLI tasks . . . 10

5 Indices and tables 13

Python Module Index 15

(4)

ii

(5)

CHAPTER

1 Development status & project plans

1.1 Code quality

Cratis source code is fully functional, tested in bigger projects.

Code coverage is 100%. Code also well-documented and compact.

1.2 History

itpeople company have developed django-based applications last 5 years, and we noticed that many parts of our application follow common patterns, use same set of django-applications, and in most cases configuration is also same.

So we decided to extract common functionality as set of reusable modules. For that purpose, we developed tiny, but powerful framework called django-cratis.

django-cratis provides a way how to group applications into reusable modules, and define sane defaults for this applications.

1.3 Plans

django-cratis is first and most important component of cratis ecosystem.

It’s more or less final, we do not plan to change it heavily, as on top of it’s shoulders staying a lot of our proprietary code. We will regularly publish improvements to django-cratis, but keeping django-cratis backward compatible as much as possible.

Beside improving django-cratis itself, we plan to publish our internal django-cratis modules, that provide lot of things:

• Django-cms integration

• Central picture storage with auto-resize right in your template code (Filer)

• Tight integration of picture storage with django-cms (django-filer)

• Filer widgets for cms (picture, file, folder)

• Frontend themes (theme = assets + templates) with inheritace support

• full localization support (templates, strings in code, models, urls, cms pages)

• django-debug toolbar integration

(6)

django-cratis Documentation, Release 0.4.2

• Nice admin theme “suit” integrationhttp://djangosuit.com/

• high-performance cherry-py web-server integration

All this packages are mature django-applications, that are configured to work together, and ready to use by adding one line of code into settings.py.

Like this:

class Dev(CratisDev):

FEATURES = (

AdminThemeSuit(), AdminArea(),

I18n(langs=[’en’, ’fr’]), Debug()

)

All packages will be published during summer 2014. But don’t wait, go and create your own, Django-cratis features.

2 Chapter 1. Development status & project plans

(7)

CHAPTER

2 Getting Started

2.1 Installation

Just use pip:

pip install django-cratis

The only-requirements that are auto-installed:

• django>=1.4

• django-configurations -http://django-configurations.readthedocs.org/en/latest/

2.2 Running cratis

django-cratis requires only two files:

cratis.yml Declares environment variables that will be passed to your application.

settings.py Your project configuration.

You can generate those files:

$ cratis-init

Now, you are ready to run application:

$ cratis runserver

Note: command “cratis” is equivalent for “python manage.py”, so you can do with cratis everything you could do with manage.py command.

2.3 Understanding structure

Now, before continue configuring our cratis based project we need to take a look at files we just generated with help of cratis-init command.

(8)

2.3.1 cratis.yml

Default content of file:

CRATIS_APP_PATH: .

DJANGO_CONFIGURATION: Dev

DJANGO_SETTINGS_MODULE: settings

This file is what cratis command is looking for when you execute cratis command (cratis.cli.cratis_cmd()).

It plays two roles:

• It is marker that indicates where your project root is located.

You can run cratis command also from sub-folders of project, it will find root automatically.

• It contains environment variables that is passed to your application.

Environment variables are heavily used by django-configurations and django itself Variables that are required:

CRATIS_APP_PATH indicates where the project root is located. Usually in same folder, where cratis.yml is, but in production it may be different.

Path specified in this variable also will be added to sys.path.

DJANGO_CONFIGURATION indicates which configuration environment to use. SeeDjango Configurations DJANGO_SETTINGS_MODULE usually it is “settings”, but you may specify any other.

2.3.2 settings.py

Default content of file:

# coding=utf-8

from cratis.settings import CratisConfig

class Dev(CratisConfig):

DEBUG = True

SECRET_KEY = ’8qIcLsQdsbI9OmRUWWnh56Qx1bSnLc’

FEATURES = (

# your features here )

class Test(Dev):

pass

class Prod(Dev):

DEBUG = False

FEATURES = Dev.FEATURES + (

# your features here )

settings.py usesDjango Configurationsto provide different configurations for different environments, otherwise it is usual django settings.

4 Chapter 2. Getting Started

(9)

The most important thing here is FEATURES. Parent class of this setting :py:class:cratis.settings.CratisConfig uses this variable to find and load your features.

The Featuresallow not to manipulate your settings directly when you need to install some new application, but delegate it to :py:class:cratis.features.Feature class.

Out of the box each Feature is able to:

• Manipulate INSTALLED_APPS, MIDDLEWARE_CLASSES, TEMPLATE_CONTEXT_PROCESSORS (Special convinient api)

• Have access and may change any of SETTINGS variables.

• Do startup actions required

2.4 Creating own Feature

Creating own feature is super-simple. Just create a new class that extends cratis.features.Feature. Then override it’s methods depending on your needs.

Example:

from cratis.features import Feature

from django.conf.urls import patterns, include

class Hotel(Feature):

def configure_settings(self, cls):

self.append_apps(cls, [’hotel’, ’imperavi’, ’django_extensions’,

’newsletter’])

def configure_urls(self, cls, urls):

urls += patterns(’’,

(r’^’, include(’hotel.urls’)),

(r’^newsletter/’, include(’newsletter.urls’)))

(10)

6 Chapter 2. Getting Started

(11)

CHAPTER

3 Licencing

django-cratis is published underSimplified BSD Licence.

3.1 Comments

Simlified BSD Licence is same as MIT, but as extra allows you to refer “django-cratis” name, author name, itpeople company name to promote your products.

For, example you can say your extensions or your own fork of cratis is compatible with initial version of django-cratis, developed by itpeople.

We intentionally do not restrict anyhow building your own business on top of cratis. If you fork cratis, add commertial support to it, we are not against, and may be even your potential clients :).

3.2 Simlified BSD Licence

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, IN- CIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSI- NESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CON- TRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAM- AGE.

The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of the FreeBSD Project.

(12)

8 Chapter 3. Licencing

(13)

CHAPTER

4 Api Detailed documentation

4.1 Feature API

class cratis.features.Feature

Feature add some concreate functionality to the BaseFeature class.

append_apps(apps)

Use this in configure_settings, to append new INSTALLED_APPS.

append_middleware(classes)

Use this in configure_settings, to append new middleware classes.

append_template_processor(processors)

Use this in configure_settings, to append new template processors.

class cratis.features.BaseFeature Basement for all the features.

configure_settings()

API method. Meant to be overridden by subsequent Features.

Called inside on_load callback.

configure_urls(urls)

API method. Meant to be overridden by subsequent Features.

Called when django imports cratis.url from cratis.urls module.

As a parameter accepts urlpatterns variable from cratis.urls get_required()

Returns list of classes of features that must be loaded before this feature can be loaded on_after_load()

Called when setting is configured on_load(loaded_features)

Loads feature. Used by settings class. By default, checks requirements and executes configure_settings() method.

As an argument accepts list of features loaded before current one.

on_startup()

Last chance to do something after settings are configured, called even later than on_after_load.

set_settings(cls)

Initialized just before configuration process start

(14)

4.2 Settings API

Default settings for cratis project

class cratis.settings.CratisConfig

Base class for Configurations that will be used with cratis.

Class contains hooks pre_setup and post_setup that will load and configure Features defined in FEATURES settings variable.

Also class defines ROOT_URLCONF settings variable, that use cratis.urls to load all urls collected from your Features. Usually you wouldn’t change this when working with cratis.

BASE_DIR just points to project directory, so you can specify paths relatively, ex:

STATIC_ROOT = os.path.join(CratisConfig.BASE_DIR, ‘some dir’) Order of Feature load is following:

•Call set_settings() on each Feature, providing class reference, so Feature can save it for future use.

•Call do_load() on each Feature, passing previously loaded feature list as an argument

•

•Django is fully configured, we run on_after_load on each Feature, so Features can do latest adjustments

•And finally call on_startup() on each feature, features shouldn’t modify anything on this step.

4.3 CLI tasks

cratis.cli.cratis_cmd()

Command that executes django ./manage.py task + loads environment variables from cratis.yml Command also can be executed from sub-folders of project.

cratis.cli.cratis_init_cmd()

Command creates new cratis project in current directory. Two files are generated:

•Empty settings file

•cratis.yml configured to serve project from current directory.

Usage:

cratis-init cratis runserver

cratis.cli.load_env()

Loads environment variables defined in cratis.yml file.

load_env() finds cratis.yml file in current directory, then in it’s parent and so on until it finds, or root dir reached (“/”). If no cratis.yml found, then error shown.

Some variables are required for cratis to work:

- CRATIS_APP_PATH - Path where cratis application is located. (default ".")

- DJANGO_SETTINGS_MODULE - Where to find settings module (Default "settings", means settings.py file in CRATIS_APP_PATH) - DJANGO_CONFIGURATION - One of Environments defined in settings.py (default "Dev")

10 Chapter 4. Api Detailed documentation

(15)

Dev mode

In development mode all valuesare meant to be used with default values, and cratis.yml is just a marker of where your project is located. Very useful when you execute cratis command from subdirectory of your project (yes, you can do this!).

Structure in this case will be following:

- myproject/

- .git

- settings.py - cratis.yml

Production mode

In production mode, cratis.yml plays important role of providing environment information.

Structure in this case will be following:

- myproject/

- src/

- .git

- settings.py - cratis.yml - cratis.yml

Note: cratis.yml that is located one level up will always get priority.

cratis.yml file contents:

CRATIS_APP_PATH’: myproject, DJANGO_CONFIGURATION’: Prod, DJANGO_SETTINGS_MODULE: settings

SOME_OTHER_ENV_VARIABLE: xxx ...

Django-Configurations highly relays on ENV variables, so you can easily redefine some settings through Env variables.

cratis.cli._find_project_env(path) Finds cratis.yml for cratis command.

Algorithm is following:

•Check current directory

•If no cratis.yml, check parent and reapeat until found –Nothing found, return None

–If found, check if parent also contains cratis.yml

*If parent contains, then return parent’s cratis.yml path

*If no, then return current dir cratis.yml

Django-cratis is a set of patterns and tools that simplify django-based application development and delivery.

Main feature of django-cratis is a way how to group applications into reusable modules, and define sane defaults for this applications, so this configuration is easily reusable across your projects.

Cratis features:

• settings.py manipulation API

(16)

• integrateddjango-configurations

• “cratis” command (no need for manage.py)

• compatible with12factor configuration

• easy to create reusable modules

12 Chapter 4. Api Detailed documentation

(17)

CHAPTER

5 Indices and tables

• genindex

• modindex

• search

(18)

14 Chapter 5. Indices and tables

(19)

Python Module Index

c

cratis.cli,10 cratis.features,9 cratis.settings,10