API¶
pyresto.core.ModelBase¶
-
class
pyresto.core.
ModelBase
¶ Bases:
abc.ABCMeta
Meta class for
Model
class. This class automagically creates the necessaryModel._path
class variable if it is not already defined. The default path pattern is/modelname/{id}
.
pyresto.core.Model¶
-
class
pyresto.core.
Model
(**kwargs)¶ Bases:
object
The base model class where every data model using pyresto should be inherited from. Uses
ModelBase
as its metaclass for various reasons explained inModelBase
.-
__init__
(**kwargs)¶ Constructor for model instances. All named parameters passed to this method are bound to the newly created instance. Any property names provided at this level which are interfering with the predefined class relations (especially for
Foreign
fields) are prepended “__” to avoid conflicts and to be used by the related relation class. For instance if your class hasfather = Foreign(Father)
andfather
is provided to the constructor, its value is saved under__father
to be used by theForeign
relationship class as the id of the foreignModel
.Constructor also tries to populate the
Model._current_path
instance variable by formattingModel._path
using the arguments provided.
-
_url_base
= None¶ The class variable that holds the bae uel for the API endpoint for the
Model
. This should be a “full” URL including the scheme, port and the initial path if there is any.
-
_path
= None¶ The class variable that holds the path to be used to fetch the instance from the server. It is a format string using the new format notation defined for
str.format()
. The primary key will be passed under the same name defined in the_pk
property and any other named parameters passed to theModel.get()
or the class constructor will be available to this string for formatting.
-
_auth
= None¶ The class variable that holds the default authentication object to be passed to
requests
. Can be overridden on either class or instance level for convenience.
-
_parser
= <function loads>¶ The class method which receives the class object and the body text of the server response to be parsed. It is expected to return a dictionary object having the properties of the related model. Defaults to a “staticazed” version of
json.loads()
so it is not necessary to override it if the response type is valid JSON.
-
_fetched
= False¶ The instance variable which is used to determine if the
Model
instance is filled from the server or not. It can be modified for certain usages but this is not suggested. If_fetched
isFalse
when an attribute, that is not in the class dictionary, tried to be accessed, the__fetch()
method is called before raising anAttributeError
.
-
_get_params
= {}¶ The instance variable which holds the additional named get parameters provided to the
Model.get()
to fetch the instance. It is used internally by theRelation
classes to get more info about the currentModel
instance while fetching its related resources.
-
classmethod
_continuator
(response)¶ The class method which receives the response from the server. This method is expected to return a continuation URL for the fetched resource, if there is any (like the next page’s URL for paginated content) and
None
otherwise. The default implementation uses the standard HTTP link header and returns the url provided under the label “next” for continuation andNone
if it cannot find this label.Parameters: response ( requests.Response
) – The response for the HTTP request made to fetch the resources.
-
_id
¶ A property that returns the instance’s primary key value.
-
_pk
¶ The class variable where the attribute name for the primary key for the
Model
is stored as a string. This property is required and not providing a default is intentional to force developers to explicitly define it on everyModel
class.
-
classmethod
_rest_call
(url, method='GET', fetch_all=True, **kwargs)¶ A method which handles all the heavy HTTP stuff by itself. This is actually a private method but to let the instances and derived classes to call it, is made
protected
using only a single_
prefix.All undocumented keyword arguments are passed to the HTTP request as keyword arguments such as method, url etc.
Parameters: fetch_all (boolean) – (optional) Determines if the function should recursively fetch any “paginated” resource or simply return the downloaded and parsed data along with a continuation URL. Returns: Returns a tuple where the first part is the parsed data from the server using Model._parser
, and the second half is the continuation URL extracted usingModel._continuator
orNone
if there isn’t any.Return type: tuple
-
classmethod
get
(*args, **kwargs)¶ The class method that fetches and instantiates the resource defined by the provided pk value. Any other extra keyword arguments are used to format the
Model._path
variable to construct the request URL.Parameters: pk (string) – The primary key value for the requested resource. Return type: Model
or None
-
pyresto.core.Auth¶
pyresto.core.AuthList¶
pyresto.core.enable_auth¶
pyresto.core.Relation¶
pyresto.core.Many¶
-
class
pyresto.core.
Many
(model, path=None, lazy=False, preprocessor=None)¶ Bases:
pyresto.core.Relation
Class for ‘many’
Relation
type which is essentially a collection for a certain model. Needs a baseModel
for the collection and a path to get the collection from. Falls back to provided model’sModel.path
if not provided.-
__init__
(model, path=None, lazy=False, preprocessor=None)¶ Constructor for Many relation instances.
Parameters: - model (Model) – The model class that each instance in the collection will be a member of.
- path (string or None) – (optional) The unicode path to fetch the collection items,
if different than
Model._path
, which usually is. - lazy (boolean) – (optional) A boolean indicator to determine the type of
the
Many
field. Normally, it will be aWrappedList
which is essentially a list. Uselazy=True
if the number of items in the collection will be uncertain or very large which will result in aLazyList
property which is practically a generator.
-
_Many__make_fetcher
(url, instance)¶ A function factory method which creates a simple fetcher function for the
Many
relation, that is used internally. TheModel._rest_call()
method defined on the models is expected to return the data and a continuation URL if there is any. This method generates a bound, fetcher function that calls the internalModel._rest_call()
function on theModel
, and processes its results to satisfy the requirements explained above.Parameters: url (unicode) – The url which the fetcher function will be bound to.
-
_with_owner
(owner)¶ A function factory method which returns a mapping/wrapping function. The returned function creates a new instance of the
Model
that theRelation
is defined with, sets its owner and “automatically fetched” internal flag and returns it.Parameters: owner (Model) – The owner Model for the collection and its items.
-
pyresto.core.Foreign¶
-
class
pyresto.core.
Foreign
(model, key_property=None, key_extractor=None, embedded=False)¶ Bases:
pyresto.core.Relation
Class for ‘foreign’
Relation
type which is essentially a reference to a certainModel
. Needs a baseModel
for obvious reasons.-
__init__
(model, key_property=None, key_extractor=None, embedded=False)¶ Constructor for the
Foreign
relations.Parameters: - model (Model) – The model class for the foreign resource.
- key_property (string or None) – (optional) The name of the property on the base
Model
which contains the id for the foreign model. - key_extractor (function(model)) – (optional) The function that will extract the id
of the foreign model from the provided
Model
instance. This argument is provided to make it possible to handle complex id extraction operations for foreign fields.
-
pyresto.core.WrappedList¶
-
class
pyresto.core.
WrappedList
(iterable, wrapper)¶ Bases:
list
Wrapped list implementation to dynamically create models as someone tries to access an item or a slice in the list. Returns a generator instead, when someone tries to iterate over the whole list.
pyresto.core.LazyList¶
-
class
pyresto.core.
LazyList
(wrapper, fetcher)¶ Bases:
object
Lazy list implementation for continuous iteration over very large lists such as commits in a large repository. This is essentially a chained and structured generator. No caching and memoization at all since the intended usage is for small number of iterations.