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:

../_images/projects_page.png

By clicking on a project you access the project’s details:

../_images/project_description.png

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:

../_images/project_releases.png

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 version 2.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 only text/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:

../_images/project_packages.png