Stage is a similar concept to Git’s one. It’s a unit of updates, so every change to the repository should be done through a stage.
It also does more than Git’s stage: Route. Routing system hides how document should be stored in the repository, and provides the natural object-mapping interface instead.
Stage also provides transactions. All operations on staged documents should be done within a transaction. You can open and close a transaction using with statement e.g.:
with stage:
subs = stage.subscriptions
stage.subscriptions = some_operation(subs)
Transaction will merge all simultaneous updates if there are multiple updates when it’s committed. You can easily achieve thread safety using transactions.
Note that it however doesn’t guarantee data integrity between multiple processes, so you have to use different session ids when there are multiple processes.
Base stage class that routes nothing yet. It should be inherited to route document types. See also Route class.
It’s a context manager, which is possible to be passed to with statement. The context maintains a transaction, that is required for all operations related to the stage:
with stage:
v = stage.some_value
stage.some_value = operate(v)
If any ongoing transaction is not present while the operation requires it, it will raise TransactionError.
Parameters: |
|
---|
(collections.Sequence) The repository key of the directory where session list are stored.
Get the current ongoing transaction. If any transaction is not begun yet, it raises TransactionError.
Returns: | the dirty buffer that should be written when the transaction is committed |
---|---|
Return type: | DirtyBuffer |
Raises TransactionError: | |
if not any transaction is not begun yet |
Read a document of document_type by the given key in the staged repository.
Parameters: |
|
---|---|
Returns: | found document instance |
Return type: | |
Raises libearth.repository.RepositoryKeyError: | |
when the key cannot be found |
Note
This method is intended to be internal. Use routed properties rather than this. See also Route.
(Repository) The staged repository.
(collections.Set) List all sessions associated to the repository. It includes the session of the current stage.
Touch the latest staged time of the current session into the repository.
Note
This method is intended to be internal.
(collections.MutableMapping) Ongoing transactions. Keys are the context identifier (that get_current_context_id() returns), and values are pairs of the DirtyBuffer that should be written when the transaction is committed, and stack information.
Save the document to the key in the staged repository.
Parameters: |
|
---|---|
Returns: | actually written document |
Return type: | MergeableDocumentElement |
Note
This method is intended to be internal. Use routed properties rather than this. See also Route.
Mapping object which represents hierarchy of routed key path.
Parameters: |
|
---|
Note
The constructor is intended to be internal, so don’t instantiate it directory. Use Route instead.
Memory-buffered proxy for the repository. It’s used for transaction buffer which maintains updates to be written until the ongoing transaction is committed.
Parameters: |
|
---|
Note
This class is intended to be internal.
Flush all buffered updates to the repository.
(Repository) The bare repository where the buffer will flush() to.
Descriptor that routes a document_type to a particular key path pattern in the repository.
key_spec could contain some format strings. Format strings can take a keyword (session) and zero or more positional arguments.
For example, if you route a document type without any positional arguments in key_spec format:
class Stage(BaseStage):
'''Stage example.'''
metadata = Route(
Metadata,
['metadata', '{session.identifier}.xml']
)
Stage instance will has a metadata attribute that simply holds Metadata document instance (in the example):
>>> stage.metadata # ['metadata', 'session-id.xml']
<Metadata ...>
If you route something with one or more positional arguments in key_spec format, then it works in some different way:
class Stage(BaseStage):
'''Stage example.'''
seating_chart = Route(
Student,
['students', 'col-{0}', 'row-{1}', '{session.identifier}.xml']
)
In the above routing, two positional arguments were used. It means that the seating_chart property will return two-dimensional mapping object (Directory):
>>> stage.seating_chart # ['students', ...]
<libearth.directory.Directory ['students']>
>>> list(stage.seating_chart)
['A', 'B', 'C', 'D']
>>> b = stage.seating_chart['B'] # ['students', 'col-B', ...]
<libearth.directory.Directory ['students', 'col-B']>
>>> list(stage.seating_chart['B'])
['1', '2', '3', '4', '5', '6']
>>> stage.seating_chart['B']['6'] \
... # ['students', 'col-B', 'row-6', 'session-id.xml']
<Student B6>
Parameters: |
|
---|
(type) The type of the routed document. It is a subtype of MergeableDocumentElement.
(collections.Sequence) The repository key pattern that might contain some format strings.
Staged documents of Earth Reader.
(SubscriptionList) The set of subscriptions.
The error that rises if there’s no ongoing transaction while it’s needed to update the stage, or if there’s already begun ongoing transaction when the new transaction get tried to begin.
Compile a format_string to regular expression pattern. For example, 'string{0}like{1}this{{2}}' will be compiled to /^string(.*?)like(.*?)this\{2\}$/.
Parameters: | format_string (str) – format string to compile |
---|---|
Returns: | compiled pattern object |
Return type: | re.RegexObject |
Identifies which context it is (greenlet, stackless, or thread).
Returns: | the identifier of the current context |
---|