Repository abstracts storage backend e.g. filesystem. There might be platforms that have no chance to directly access file system e.g. iOS, and in that case the concept of repository makes you to store data directly to Dropbox or Google Drive instead of filesystem. However in the most cases we will simply use FileSystemRepository even if data are synchronized using Dropbox or rsync.
In order to make the repository highly configurable it provides the way to lookup and instantiate the repository from url. For example, the following url will load FileSystemRepository which sets path to /home/dahlia/.earthreader/:
[libearth.repositories] file = libearth.repository:FileSystemRepository
Note that the entry point name (file in the above example) becomes the url scheme to lookup the corresponding repository class (libearth.repository.FileSystemRepository in the above example).
Read a file through Iterator protocol, with automatic closing of the file when it ends.
Raised when a given path does not exist.
Builtin implementation of Repository interface which uses the ordinary file system.
Raised when a given path is not a directory.
Repository interface agnostic to its underlying storage implementation. Stage objects can deal with documents to be stored using the interface.
Every content in repositories is accessible using keys. It actually abstracts out “filenames” in “file systems”, hence keys share the common concepts with filenames. Keys are hierarchical, like file paths, so consists of multiple sequential strings e.g. ['dir', 'subdir', 'key']. You can list() all subkeys in the upper key as well e.g.:
Return whether the key exists or not. It returns False if it doesn’t exist instead of raising RepositoryKeyError.
|Parameters:||key (collections.Sequence) – the key to find whether it exists|
|Returns:||True only if the given key exists, or False if not exists|
Create a new instance of the repository from the given url. It’s used for configuring the repository in plain text e.g. *.ini.
|Parameters:||url (urllib.parse.ParseResult) – the parsed url tuple|
|Returns:||a new repository instance|
|when the given url is not invalid|
List all subkeys in the key.
|Parameters:||key (collections.Sequence) – the incomplete key that might have subkeys|
|Returns:||the set of subkeys (set of strings, not set of string lists)|
|the key cannot be found in the repository, or it’s not a directory|
Read the content from the key.
|Parameters:||key (collections.Sequence) – the key which stores the content to read|
|Returns:||byte string chunks|
|the key cannot be found in the repository, or it’s not a file|
Generate a url that from_url() can accept. It’s used for configuring the repository in plain text e.g. *.ini. URL scheme is determined by caller, and given through argument.
|Parameters:||scheme – a determined url scheme|
|Returns:||a url that from_url() can accept|
Write the iterable into the key.
Exception which rises when the requested key cannot be found in the repository.
(collections.Sequence) The requested key.
Load the repository instance from the given configuration url.
If setuptools is not installed it will only support file:// scheme and FileSystemRepository.
the loaded repository instance