Package pyperry :: Module base :: Class Base

Class Base

object --+
         |
        Base

The Base class for all models using pyperry.

Base defines the functionality of a pyperry model. All models should inherit (directly or indirectly) from Base. For a basic overview of usage, check out the docs on the pyperry module.

Configuration Overview

Configuration is done through various class methods on the model. These could be set anywhere, but conventionally they are set in a config method on the class. This method is run when a class is created with the newly created class as an argument. Thus, configuration can be done like this:

   class Animal(pyperry.base.Base):
       def config(cls):
           cls.attributes 'id', 'name', 'mammal'
           cls.configure('read', type='bertrpc')
           cls.add_middleware('read', MyMiddleware, config1='val')

           cls.has_many('friendships', class_name='Friendship')

           cls.scope('mammal', where={ 'mammal': true })

Any class configuration can be done in this method.

Querying

Queries can be built by chaining calls to scopes or query methods. For example:

   Person.where({ 'first_name': 'Bob' }).order('last_name')

This generates a query for all Person objects with the first name "Bob" ordered by their last name. Each query method returns a new Relation object with the new query parameters applied. This allows the continued chaining.

A Relation object is a sequence-like object behaving much like a list. The query will be run the first time the object is treated like a list, and the records will be used for the expression. For example:

   query = Animal.where({ 'type': 'Platypus' })

   # Array comprehensions and for loops
   for animal in query:
       print animal.name + " is a platypus.  They don't do much."

   # Compares type and attributes of objects for equality
   object in query
   object not in query

   # Indexing, slicing, step slicing
   query[0]
   query[0:3]
   query[0:3:2]

   # Other
   len(query)

In this example the query is executed before running the for loop, and all subsequent calls use that result. Queries will not be run until you need them so unused queries don't hurt performance. If you would like to force a query to run and retreive the records in a list object use the Relation.all() method, or to receive the object itself in single result queries use the Relation.first() method.

Persistence

Pyperry provides an interface for creating, updating, and deleting models when a write adapter is configured. A model can be initialized as a "new" record (default) or a "stored" record and is determined by the new_record attribute. This changes the behavior of the save operation. A "new" record is created and a "stored" record is updated. Also, a "new" record cannot be deleted as it does not yet exist in the database. See the individual persistence methods for more information

Scopes

Scopes allow you to specify prebuilt views of your data. Scopes, like query methods, can be applied simply by chaining calls on instances of Relation or the Base class. Scopes are created through the scope() class method (conventionally within the _config method):

   cls.scope('ordered', order='type, name')
   cls.scope('platypus', where={ 'type': 'platypus' })
   cls.scope('perrys', where={ 'name': 'perry' })
   cls.scope('agentp', cls.perrys().platypus())

These scopes can now be used in queries along with query methods and chained together to make powerful queries:

   # Ordered animals with type 'platypus' named 'perry'
   Animal.ordered().agentp()

Scopes can also accept arguments by defining a lambda or function to be called when the scope is invoked:

   @cls.scope
   def name_is(rel, name):
       return rel.where({ 'name': name })

   # This can also be written:
   cls.scope('name_is', lambda(rel, name): rel.where({ 'name': name }))

   # This allows:
   Animal.name_is('perry')

Associations

Associations allow you to define foreign key relationships between two models, the target (model on which the association is defined) and the source (model from which the data will come). There are two basic kinds of associations: has and belongs. A has relationship means the foreign_key lives on the source model. A belongs relationship means the foreign_key lives on target model.

Imagine a blog. A blog has many articles and an article belongs to an author. You might model this structure with Blog, Article and Person classes. Associations are conventionally defined in the _config method for each class, but to save space we'll just show the association definition for each class:

   Blog.has_many('articles', class_name='Article')
   Article.belongs_to('blog', class_name='Blog')
   Article.belongs_to('author', class_name='Person')

Assuming you have an instance of Blog called blog you could then reference these associations like this:

   # An ordered list of articles on this blog
   articles = blog.authors().ordered()
   # The author of the first article
   articles[0].author()

Note that the has_many association returns a Relation object allowing you to apply query methods and scopes to the association before executing the query.

For more information on Associations see the individual association methods.

Nested Classes
	__metaclass__ The Metaclass for Base

Instance Methods

__init__(self, attributes={}, new_record=True, **kwargs)
Initialize a new pyperry object with attributes source code

reload(self)
Refetch the attributes for this object from the read adapter

source code

frozen(self)
Returns True if this instance is frozen and cannot be saved.

source code

freeze(self)
Marks this instance as being frozen, which will cause all future writes and deletes to fail.

source code

__repr__(self)
Return a string representation of the object

source code

__eq__(self, compare)
Compare equality of an object by its attributes

source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __sizeof__, __str__, __subclasshook__

Attribute access

__getitem__(self, key)
Adds dict like attribute reading source code

__setitem__(self, key, value)
Adds dict like attribute writing source code

__getattr__(self, key)
Dynamic attribute / association reading

source code

__setattr__(self, key, value)
Dynamic attribute setting

source code

pk_attr(self)
A shortcut method from retrieving the name of this model's primary key attribute.

source code

pk_value(self)
A shortcut method for retrieving the value stored in this model's primary key attribute.

source code

Persistence

set_attributes(self, attributes)
Set the attributes of the object using the provided dictionary.

source code

save(self)
Save the current value of the model's data attributes through the write adapter.

source code

update_attributes(self, attributes=None, **kwargs)
Update the attributes with the given dictionary or keywords and save the model.

source code

delete(self)
Removes this model from the data store

source code

Class Methods

fetch_records(cls, relation)
Execute query using relation on the read adapter stack

source code

__configmodel__(cls)

source code

Configuration

configure(cls, adapter_type, config=None, **kwargs)
Method for setting adapter configuration options.

source code

add_middleware(cls, adapter_type, klass, options=None, **kwargs)
Add a middleware to the given adapter

source code

add_processor(cls, adapter_type, klass, options=None, **kwargs)
Add a processor to the given adapter

source code

adapter(cls, adapter_type)
Returns the adapter specified by adapter_type source code

define_attributes(cls, *attributes)
Define available attributes for a model.

source code

attributes(cls, *attributes)
Define available attributes for a model.

source code

primary_key(cls)
Returns the attribute name of the model's primary key.

source code

set_primary_key(cls, attr_name)
Set the name of the primary key attribute for the model.

source code

Scoping

relation(cls)
A base instance of Relation for this model. source code

current_scope(cls)
Base instance of Relation after default scopes are applied. source code

scoped(cls)
Unique instance of Relation to build queries on. source code

default_scope(cls, *args, **kwargs)
Add a default scoping for this model.

source code

unscoped(cls, function)
Execute function without default scopes source code

scope(cls, name_or_func, *args, **kwargs)
Defines a scope on the given model.

source code

Association Declaration

belongs_to(cls, id, **kwargs)
Create a belongs association

source code

has_many(cls, id, **kwargs)
Create has collection association

source code

has_one(cls, id, **kwargs)
Create singular has association

source code

Class Variables
	adapter_config = `{}`
	defined_associations = `{}`
	defined_attributes = `set([])`

Properties
Inherited from `object`: `__class__`

Method Details

Class Base

Configuration Overview

Querying

Persistence

Scopes

Associations

__init__(self, attributes={}, new_record=True, **kwargs) (Constructor)

__getitem__(self, key) (Indexing operator)

__setitem__(self, key, value) (Index assignment operator)

__getattr__(self, key) (Qualification operator)

__setattr__(self, key, value)

set_attributes(self, attributes)

save(self)

update_attributes(self, attributes=None, **kwargs)

delete(self)

configure(cls, adapter_type, config=None, **kwargs) Class Method

add_middleware(cls, adapter_type, klass, options=None, **kwargs) Class Method

add_processor(cls, adapter_type, klass, options=None, **kwargs) Class Method

adapter(cls, adapter_type) Class Method

define_attributes(cls, *attributes) Class Method

attributes(cls, *attributes) Class Method

set_primary_key(cls, attr_name) Class Method

fetch_records(cls, relation) Class Method

relation(cls) Class Method

current_scope(cls) Class Method

scoped(cls) Class Method

default_scope(cls, *args, **kwargs) Class Method

unscoped(cls, function) Class Method

scope(cls, name_or_func, *args, **kwargs) Class Method

belongs_to(cls, id, **kwargs) Class Method

has_many(cls, id, **kwargs) Class Method

has_one(cls, id, **kwargs) Class Method

__repr__(self) (Representation operator)

init(self, attributes=`{}`, new_record=True, **kwargs)
(Constructor)

getitem(self, key)
(Indexing operator)

setitem(self, key, value)
(Index assignment operator)

getattr(self, key)
(Qualification operator)

setattr(self, key, value)

configure(cls, adapter_type, config=None, **kwargs)
Class Method

add_middleware(cls, adapter_type, klass, options=None, **kwargs)
Class Method

add_processor(cls, adapter_type, klass, options=None, **kwargs)
Class Method

adapter(cls, adapter_type)
Class Method

define_attributes(cls, attributes)
Class Method*

attributes(cls, attributes)
Class Method*

set_primary_key(cls, attr_name)
Class Method

fetch_records(cls, relation)
Class Method

relation(cls)
Class Method

current_scope(cls)
Class Method

scoped(cls)
Class Method

default_scope(cls, *args, **kwargs)
Class Method

unscoped(cls, function)
Class Method

scope(cls, name_or_func, *args, **kwargs)
Class Method

belongs_to(cls, id, **kwargs)
Class Method

has_many(cls, id, **kwargs)
Class Method

has_one(cls, id, **kwargs)
Class Method

repr(self)
(Representation operator)