Fields API¶

This is the base class of all StdNet Fields. Each field is specified as a StdModel class attribute.

index¶

Probably the most important field attribute, it establish if the field creates indexes for queries. If you don’t need to query the field you should set this value to False, it will save you memory.

Note

if index is set to False executing queries against the field will throw a stdnet.QuerySetError exception. No database queries are allowed for non indexed fields as a design decision (explicit better than implicit).

Default True.

unique¶

If True, the field must be unique throughout the model. In this case Field.index is also True. Enforced at stdnet.BackendDataServer level.

Default False.

primary_key¶

If True, this field is the primary key for the model. A primary key field has the following properties:

• Field.unique is also True.
• There can be only one in a model.
• It’s attribute name in the model must be id.
• If not specified a AutoIdField will be added.

Default False.

required¶

If False, the field is allowed to be null.

Default True.

default¶

Default value for this field. It can be a callable attribute with arity 0.

Default None.

name¶

Field name, created by the odm at runtime.

attname¶

The attribute name for the field, created by the get_attname() method at runtime. For most field, its value is the same as the name. It is the field sorted in the backend database.

model¶

The StdModel holding the field. Created by the odm at runtime.

charset¶

The charset used for encoding decoding text.

hidden¶

If True the field will be hidden from search algorithms.

Default False.

python_type¶

The python type for the Field.

as_cache¶

If True the field contains data which is considered cache and therefore always reproducible. Field marked as cache, have required always False.

This attribute is used by the StdModel.fieldvalue_pairs method which returns a dictionary of field names and values.

Default False.

register_with_model(name, model)¶

Called during the creation of a the StdModel class when Metaclass is initialised. It fills Field.name and Field.model. This is an internal function users should never call.

add_to_fields()¶

Add this Field to the fields of model.

get_attname()¶

Generate the attname at runtime

get_cache_name()¶

name for the private attribute which contains a cached value for this field. Used only by realted fields.

id(obj)¶

Field id for object obj, if applicable. Default is None.

get_default()¶

Returns the default value for this field.

get_lookup(remaining, errorClass=<class 'ValueError'>)¶

called by the Query method when it needs to build lookup on fields with additional nested fields. This is the case of ForeignKey and JSONField.

Parameters:	remaining – the double underscored fields if this Field errorClass – Optional exception class to use if the remaining field is not valid.

get_value(instance, *bits)¶

Retrieve the value Field from a StdModel instance.

Parameters:	instance – The StdModel instance invoking this function. bits – Additional information for nested fields which derives from the double underscore notation.
Returns:	the value of this Field in the instance. can raise AttributeError.

This method is used by the StdModel.get_attr_value() method when retrieving values form a StdModel instance.

set_value(instance, value)¶

Set the value for this Field in a instance of a StdModel.

set_get_value(instance, value)¶

Set the value for this Field in a instance of a StdModel and return the database representation. This method is invoked by the validation lagorithm before saving instances.

to_python(value, backend=None)¶

Converts the input value into the expected Python data type, raising stdnet.FieldValueError if the data can’t be converted. Returns the converted value. Subclasses should override this.

serialise(value, lookup=None)¶

Convert value to a valid database representation for this field.

This method is invoked by the Query algorithm.

json_serialise(value)¶

Return a representation of this field which is compatible with JSON.

scorefun(value)¶

Function which evaluate a score from the field value. Used by the ordering alorithm

The base class for fields containing atoms. An atom is an irreducible value with a specific data type. it can be of four different types:

• boolean
• integer
• date
• datetime
• floating point
• symbol

Virtual base class for Field which are proxies to data structures such as List, Set, Zset, HashTable and timeseries TS.

Sometimes you want to structure your data model without breaking it up into multiple entities. For example, you might want to define model that contains a list of messages an instance receive:

from stdnet import orm

class MyModel(odm.StdModel):
    ...
    messages = odm.ListField()

By defining structured fields in a model, an instance of that model can access a stand alone structure in the back-end server with very little effort:

m = MyModel.objects.get(id=1)
m.messages.push_back('Hello there!')

Behind the scenes, this functionality is implemented by Python descriptors.

Additional Field attributes

relmodel¶

Optional StdModel class contained in the structure.

value_pickler¶

An stdnet.utils.encoders.Encoder used to encode and decode values.

Default: stdnet.utils.encoders.Json.

pickler¶

Same as the value_pickler attribute, this serializer is applied to keys, rather than values, in StructureField of PairMixin type (these include HashField, TimeSeriesField and ordered SetField)

Default: None.

class_field¶

If True this StructureField is a class field (it belongs to the model class rather than model instances). For example:

class MyModel(odm.StdModel):
    ...
    updates = odm.List(class_field=True)

MyModel.updates.push_back(1)

Default: False.

structure_class()¶

Returns the Structure class for this field.

An integer AtomField.

python_type¶

alias of int

A boolean AtomField

python_type¶

alias of bool

An AtomField for primary keys which are automatically generated by the backend server. You usually won’t need to use this directly; a primary_key field of this type, named id, will automatically be added to your model if you don’t specify otherwise. Check the primary key tutorial for further information on primary keys.

An floating point AtomField. By default its Field.index is set to False.

python_type¶

alias of float

An AtomField which contains a symbol. A symbol holds a unicode string as a single unit. A symbol is irreducible, and are often used to hold names, codes or other entities. They are indexes by default.

python_type¶

alias of str

A text SymbolField which is never an index. It contains unicode and by default and Field.required is set to False.

A CharField which contains binary data. In python this is converted to bytes.

python_type¶

alias of bytes

An AtomField represented in Python by a datetime.date instance.

python_type¶

alias of date

A date AtomField represented in Python by a datetime.datetime instance.

python_type¶

alias of datetime

This field can be used when an instance of a model is uniquely identified by a combination of two or more Field in the model itself. It requires a number of positional arguments greater or equal 2. These arguments must be fields names in the model where the CompositeIdField is defined.

fields¶

list of Field names which are used to uniquely identify a model instance

Check the composite id tutorial for more information and tips on how to use it.

A JSON field which implements automatic conversion to and from an object and a JSON string. It is the responsability of the user making sure the object is JSON serializable.

There are few extra parameters which can be used to customize the behaviour and how the field is stored in the back-end server.

as_string¶

A boolean indicating if data should be serialized into a single JSON string or it should be used to create several fields prefixed with the field name and the double underscore __.

Default True.

Effectively, a JSONField with as_string attribute set to False is a multifield, in the sense that it generates several field-value pairs. For example, lets consider the following:

class MyModel(odm.StdModel):
    name = odm.SymbolField()
    data = odm.JSONField(as_string=False)

And:

>>> m = MyModel(name='bla',
...             data={'pv': {'': 0.5, 'mean': 1, 'std': 3.5}})
>>> m.cleaned_data
{'name': 'bla', 'data__pv': 0.5, 'data__pv__mean': '1',
 'data__pv__std': '3.5', 'data': '""'}
>>>

The reason for setting as_string to False is to allow the JSONField to define several fields at runtime, without introducing new Field in your model class. These fields behave exactly like standard fields and therefore you can, for example, sort queries with respect to them:

>>> MyModel.objects.query().sort_by('data__pv__std')
>>> MyModel.objects.query().sort_by('-data__pv')

which can be rather useful feature.

A field which implements automatic conversion to and form a picklable python object. This field is python specific and therefore not of much use if accessed from external programs. Consider the ForeignKey or JSONField fields as more general alternatives.

A filed which can be used to store the model classes (not only StdModel models). If a class has a attribute _meta with a unique hash attribute hash and it is registered in the model hash table, it can be used.

A field defining a one-to-many objects

relationship.

Requires a positional argument: the class to which the model is related. For example:

class Folder(odm.StdModel):
    name = odm.SymobolField()

class File(odm.StdModel):
    folder = odm.ForeignKey(Folder, related_name = 'files')

To create a recursive relationship, an object that has a many-to-one relationship with itself use:

odm.ForeignKey('self')

Behind the scenes, stdnet appends “_id” to the field name to create its field name in the back-end data-server. In the above example, the database field for the File model will have a folder_id field.

related_name¶

Optional name to use for the relation from the related object back to self.

python_type¶

alias of int

proxy_class¶

alias of LazyForeignKey

related_manager_class¶

alias of One2ManyRelatedManager

A many-to-many relationship. Like ForeignKey, it requires a positional argument, the class to which the model is related and it accepts related_name as extra argument.

related_name¶

Optional name to use for the relation from the related object back to self. For example:

class Group(odm.StdModel):
    name = odm.SymbolField(unique=True)

class User(odm.StdModel):
    name = odm.SymbolField(unique=True)
    groups = odm.ManyToManyField(Group, related_name='users')

To use it:

>>> g = Group(name='developers').save()
>>> g.users.add(User(name='john').save())
>>> u.users.add(User(name='mark').save())

and to remove:

>>> u.following.remove(User.objects.get(name='john'))

through¶

An optional StdModel to use for creating the many-to-many relationship can be passed to the constructor, via the through keyword. If such a model is not passed, under the hood, a ManyToManyField creates a new model with name constructed from the field name and the model holding the field. In the example above it would be group_user. This model contains two ForeignKeys, one to model holding the ManyToManyField and the other to the related_model.

A field maintaining a list of values.

When accessed from the model instance, it returns a of List structure. For example:

class UserMessage(odm.StdModel):
    user = odm.SymbolField()
    messages = odm.ListField()

Lets register it with redis:

>>> odm.register(UserMessage, "redis://127.0.0.1:6379?db=11")
'redis db 7 on 127.0.0.1:6379'

Can be used as:

>>> m = UserMessage(user='pippo').save()
>>> m.messages.push_back("adding my first message to the list")
>>> m.messages.push_back("ciao")
>>> type(u.messages)
<class 'stdnet.odm.struct.List'>
>>> u.messages.size()
2

A field maintaining an unordered or ordered collection of values. It is initiated without any argument other than an optional model class:

class User(odm.StdModel):
    username  = odm.AtomField(unique = True)
    password  = odm.AtomField()
    following = odm.SetField(model = 'self')

It can be used in the following way:

>>> user = User(username='lsbardel', password='mypassword').save()
>>> user2 = User(username='pippo', password='pippopassword').save()
>>> user.following.add(user2)
>>> user.save()
>>> user2 in user.following
True

ordered¶

A flag indicating if the elements in this set are ordered with respect a score. If ordered, the StructureField.structure_class() method returns a Zset otherwise a Set. Default False.

A Hash table field, the networked equivalent of a python dictionary. Keys are string while values are string/numeric. it returns an instance of HashTable structure.

A timeseries field based on TS data structure.