-
Notifications
You must be signed in to change notification settings - Fork 66
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Docs usage #210
Closed
Closed
Docs usage #210
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -18,6 +18,7 @@ Invenio-Files-REST. | |
.. toctree:: | ||
:maxdepth: 2 | ||
|
||
overview | ||
installation | ||
configuration | ||
usage | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,136 @@ | ||
.. | ||
This file is part of Invenio. | ||
Copyright (C) 2015-2019 CERN. | ||
|
||
Invenio is free software; you can redistribute it and/or modify it | ||
under the terms of the MIT License; see LICENSE file for more details. | ||
|
||
|
||
Overview | ||
ntarocco marked this conversation as resolved.
Show resolved
Hide resolved
|
||
======== | ||
Invenio-Files-REST is a files storage module. It allows you to store and | ||
retrieve files in a similar way to Amazon S3 APIs. | ||
|
||
Before getting started a brief overview will introduce you to the key concepts | ||
and terminology of the module. | ||
|
||
|
||
.. figure:: _static/InvenioFilesREST.png | ||
:alt: Overview of InvenioFilesREST | ||
|
||
Overview of Invenio-Files-REST | ||
|
||
|
||
Location | ||
-------- | ||
The first concept to introduce is :code:`Location`. Locations are used to | ||
represent different storage systems. :code:`Location` has a :code:`name` and a | ||
:code:`URI` which could be a path in a local directory or a URI on a remote | ||
system. It is required to define at least one default location. | ||
|
||
See the API section of :py:class:`invenio_files_rest.models.Location` for more | ||
information. | ||
|
||
|
||
Storage | ||
------- | ||
A backend :code:`Storage` provides the interface to interact with a | ||
:code:`Location` and perform basic operations with files, such as retrieve, | ||
store or delete. | ||
|
||
By default, Invenio-Files-REST provides a simple local files storage | ||
:py:class:`invenio_files_rest.storage.PyFSFileStorage`. You can define | ||
your own storage with the configuration :py:data:`invenio_files_rest.config.FILES_REST_STORAGE_FACTORY`. | ||
|
||
An example of a remote storage system can be found at | ||
`Invenio-S3 <https://invenio-s3.readthedocs.io/>`_ which offers integration | ||
with any S3 REST API compatible object storage. | ||
|
||
See the API section of :py:class:`invenio_files_rest.storage` for more | ||
information. | ||
|
||
|
||
FileInstance | ||
------------ | ||
Files on disk are represented with :code:`FileInstance`. A file instance | ||
records the path to the file, but also its `Storage`, size and checksum of the | ||
file on disk. | ||
|
||
See the API section of :py:class:`invenio_files_rest.models.FileInstance` for | ||
more information. | ||
|
||
|
||
Object | ||
------ | ||
An :code:`Object` is an abstract representation of the file metadata: it | ||
doesn't come with its own data model but it is defined by | ||
:code:`ObjectVersion`. | ||
|
||
|
||
ObjectVersion | ||
------------- | ||
An :code:`ObjectVersion` represents a version of an :code:`Object` at a | ||
specific point in time. It contains the :code:`FileInstance` that describes and | ||
a set of metadata. | ||
|
||
When it has no :code:`FileInstance`, it marks a deletion of a file as a delete | ||
marker (or soft deletion). | ||
|
||
The latest version of the file is referred to as the :code:`HEAD`. | ||
|
||
Object version are very useful to perform operation on files metadata without | ||
accessing directly to the storage. For example, multiple :code:`ObjectVersion` | ||
can point to the same :code:`FileInstance`, allowing operations to be | ||
performed more efficiently, such as snapshots without duplicating files or | ||
migrating data. | ||
|
||
See the API section of :py:class:`invenio_files_rest.models.ObjectVersion` for | ||
more information. | ||
|
||
|
||
ObjectVersionTag | ||
---------------- | ||
|
||
:code:`ObjectVersionTag` is useful to store extra information for an | ||
:code:`ObjectVersion`. | ||
|
||
A :code:`ObjectVersionTag` is in the form of :code:`key: value` pair and an | ||
:code:`ObjectVersion` can have multiple :code:`ObjectVersionTag`. | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Object Tags? |
||
See the API section of | ||
:py:class:`invenio_files_rest.models.ObjectVersionTag` for more information. | ||
|
||
|
||
Bucket | ||
------ | ||
Consider the :code:`Bucket` as a container for :code:`ObjectVersion` objects. | ||
Just as in a computer, files are contained inside folders, each | ||
:code:`ObjectVersion` has to be contained in a :code:`Bucket`. | ||
|
||
The :code:`Bucket` is identified by an unique ID and is created in a | ||
given :code:`Location` with a given :code:`Storage`. | ||
|
||
:code:`ObjectVersion` are uniquely identified within a bucket by string keys. | ||
|
||
.. .note:: | ||
|
||
:code:`Objects` inside a :code:`Bucket` do not necessarily have the same | ||
:code:`Location` or :code:`Storage` class as the :code:`Bucket`. | ||
|
||
A bucket can also be marked as deleted, in which case the contents become | ||
inaccessible. It can also be permanently removed: in this case, all contained :code:`ObjectVersions` will be also deleted. | ||
|
||
See the API section of :py:class:`invenio_files_rest.models.Bucket` for more | ||
information. | ||
|
||
|
||
BucketTag | ||
--------- | ||
Similarly to :code:`ObjectVersionTag`, a :code:`BucketTag` is useful to store | ||
extra information for a :code:`Bucket`. | ||
|
||
A :code:`BucketTag` is in the form of :code:`key: value` pair and a | ||
:code:`Bucket` can have multiple :code:`BucketTag`. | ||
|
||
See the API section of :py:class:`invenio_files_rest.models.BucketTag` for | ||
more information. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should enrich this to something similar to: https://invenio-assets.readthedocs.io/en/latest/installation.html
Let's see together what to put exactly.