Core concepts¶
The fundamentals behind pryv mechanisms are pretty simple. In this section, we provide details on the model used by pryv and explain what each entity was designed for and how to manage it.
These were not invented by pryv’s creators. They are only formalized here, for their use in the context of pryv.
Overview¶
The following figure provides an overview of the different entities and their relation. A detailed description is provided for each of them below.
Project¶
A project is a set of source files that aim at solving a problem. In pryv, a project is a collection of releases and is identified by its name.
Different projects in pryv must have different names. The name used by pryv to resolve a
project is its normalized Python name (see
PEP 503 for details). Hence several projects
with names that evaluate to the same normalized name are considered as the same project by pryv
(for example my-project
, my.project
and My_Project
all evaluate to the normalized name
my-project
and thus are considered as a single project named my-project
).
When uploading a package to pryv, you automatically create a project and its associated release.
You can see all projects that were created in your pryv server by browsing the explorer to the projects page. The following image shows an example:
By clicking on a project you access the project’s details:
Release¶
A release is a snapshot of a project at a given time. It is uniquely identified within a project by its version number (see PEP 440 for details).
When uploading a package to pryv, you automatically create a release. The first time you upload a package, you will create a release for a project. Subsequent package uploads will create a new release only for releases with a new version number (i.e. only if no release with the same version number exist in pryv).
You can see all releases of a project by going to the Releases tab of the project’s page:
Metadata¶
Metadata provide information on a release (see PEP 566 for details). They are loaded when uploading a package to pryv. Subsequent uploads of packages to the same release with different metadata overwrite the original metadata.
Metadata are defined in the setup.py
file of a project (see something for
details). Using a tool, such as Twine or
Setuptools, for uploading your packages ensures metadata are
correctly provided.
The list of metadata fields supported by pryv is:
metadata_version
: Only metadata with version2.1
were tested. Other versions of metadata are not guaranteed to work.name
: This field is used to determine the name of the project.version
: This field is used to determine the version of the release.summary
description
: This field is used to display the project’s description.description_content_type
: This field is used to determine the description’s content type. Currently onlytext/x-rst
is supported. Other content types might be incorrectly rendered.keywords
home_page
download_url
author
author_email
maintainer
maintainer_email
license
classifiers
requires_dist
requires_python
requires_external
project_url
provides_extra
Package¶
A package is a file that contains everything required for others to use a specific release of a project. There might be several packages per project’s release. This is up to you.
Read the uploading and using sections to learn more about how to upload and use packages to and from pryv.
You can see all packages that belong to a project’s release by going to the Packages tab of the project’s page: