API Documentation

Anitya provides several APIs for users.

HTTP API v2

The token for API could be obtained from settings page in Anitya web interface. This token needs to be provided in Authorization header of the request. See request examples bellow.

GET /api/v2/packages/

List all packages.

Example request:

GET /api/v2/packages/?name=0ad&distribution=Fedora HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: localhost:5000
User-Agent: HTTPie/0.9.4

Example response:

HTTP/1.0 200 OK
Content-Length: 181
Content-Type: application/json
Date: Mon, 15 Jan 2018 20:21:44 GMT
Server: Werkzeug/0.14.1 Python/2.7.14

{
    "items": [
        {
            "distribution": "Fedora",
            "name": "python-requests"
            "project": "requests",
            "ecosystem": "pypi",
            "version": "2.28.1",
            "stable_version": "2.28.1"
        }
    ],
    "items_per_page": 25,
    "page": 1,
    "total_items": 1
}
Query Parameters:
  • page (int) – The package page number to retrieve (defaults to 1).

  • items_per_page (int) – The number of items per page (defaults to 25, maximum of 250).

  • distribution (str) – Filter packages by distribution.

  • name (str) – The name of the package.

Status Codes:
  • 200 OK – If all arguments are valid. Note that even if there are no projects, this will return 200.

  • 400 Bad Request – If one or more of the query arguments is invalid.

POST /api/v2/packages/

Create a new package associated with an existing project and distribution.

Example request:

POST /api/v2/packages/ HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Authorization: Token gAOFi2wQPzUJFIfDkscAKjbJfXELCz0r44m57Ur2
Connection: keep-alive
Content-Length: 120
Content-Type: application/json
Host: localhost:5000
User-Agent: HTTPie/0.9.4

{
    "distribution": "Fedora",
    "package_name": "python-requests",
    "project_ecosystem": "pypi",
    "project_name": "requests"
}
HTTP/1.0 201 CREATED
Content-Length: 69
Content-Type: application/json
Date: Mon, 15 Jan 2018 21:49:01 GMT
Server: Werkzeug/0.14.1 Python/2.7.14

{
    "distribution": "Fedora",
    "name": "python-requests"
}
Request Headers:
Request JSON Object:
  • distribution (string) – The name of the distribution that contains this package.

  • package_name (string) – The name of the package in the distribution repository.

  • project_name (string) – The project name in Anitya.

  • project_ecosystem (string) – The ecosystem the project is a part of. If it’s not part of an ecosystem, use the homepage used in the Anitya project.

Status Codes:
GET /api/v2/projects/

Lists all projects.

Example request:

GET /api/v2/projects/?items_per_page=1&page=2 HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: localhost:5000
User-Agent: HTTPie/0.9.4

Example response:

HTTP/1.0 200 OK
Content-Length: 676
Content-Type: application/json
Date: Fri, 24 Mar 2017 18:44:32 GMT
Server: Werkzeug/0.12.1 Python/2.7.13

{
    "items": [
        {
            "backend": "Sourceforge",
            "created_on": 1412174943.0,
            "ecosystem": "https://sourceforge.net/projects/zero-install",
            "homepage": "https://sourceforge.net/projects/zero-install",
            "id": 1,
            "name": "0install",
            "regex": "",
            "updated_on": 1482495004.0,
            "version": "2.12",
            "version_url": "zero-install",
            "versions": [
                "2.12",
                "2.11",
                "2.10",
                "2.9.1",
                "2.9",
                "2.8",
                "2.7"
            ],
            "stable_versions": [
                "2.12",
                "2.11",
                "2.10",
                "2.9.1",
                "2.9",
                "2.8",
                "2.7"
            ]
        }
    ],
    "items_per_page": 1,
    "page": 2,
    "total_items": 13468
}
Query Parameters:
  • page (int) – The project page number to retrieve (defaults to 1).

  • items_per_page (int) – The number of items per page (defaults to 25, maximum of 250).

  • ecosystem (string) – The project ecosystem (e.g. pypi, rubygems). If the project is not part of a language package index, use its homepage.

  • name (string) – The project name to filter the query by.

Status Codes:
  • 200 OK – If all arguments are valid. Note that even if there are no projects matching the query, this will return 200.

  • 400 Bad Request – If one or more of the query arguments is invalid.

POST /api/v2/projects/

Create a new project.

Example Request:

POST /api/v2/projects/ HTTP/1.1
Authorization: token hxPpKow7nnT6UTAEKMtQwl310P6GtyqV8DDbexnk
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 114
Content-Type: application/json
Host: localhost:5000
User-Agent: HTTPie/0.9.4

{
    "backend": "custom",
    "homepage": "https://example.com/test",
    "name": "test_project",
    "version_prefix": "release-"
}

Example Response:

HTTP/1.0 201 CREATED
Content-Length: 276
Content-Type: application/json
Date: Sun, 26 Mar 2017 15:56:30 GMT
Server: Werkzeug/0.12.1 Python/2.7.13

{
    "backend": "PyPI",
    "created_on": 1490543790.0,
    "homepage": "http://python-requests.org",
    "id": 13857,
    "name": "requests",
    "regex": null,
    "updated_on": 1490543790.0,
    "version": null,
    "version_url": null,
    "versions": [],
    "stable_versions": []
}
Query Parameters:
  • access_token (string) – Your API access token.

Request JSON Object:
  • name (string) – The project name

  • homepage (string) – The project homepage URL

  • backend (string) – The project backend (github, folder, etc.).

  • version_url (string) – The URL to fetch when determining the project version (defaults to null).

  • version_scheme (string) – The project version scheme. If missing, it’s set to “RPM”.

  • version_pattern (string) – The version pattern for calendar version scheme.

  • version_prefix (string) – The project version prefix, if any. For example, some projects prefix with “v”.

  • pre_release_filter (string) – Filter for unstable versions.

  • version_filter (string) – Filter for blacklisted versions.

  • regex (string) – The regex to use when searching the version_url page.

  • insecure (bool) – When retrieving the versions via HTTPS, do not validate the certificate (defaults to false).

  • check_release (bool) – Check the release immediately after creating the project.

Status Codes:
  • 201 Created – When the project was successfully created.

  • 400 Bad Request – When required arguments are missing or malformed.

  • 401 Unauthorized – When your access token is missing or invalid, or when the server is not configured for OpenID Connect. The response will include a JSON body describing the exact problem.

  • 409 Conflict – When the project already exists.

GET /api/v2/versions/

Lists all versions on project.

Example request:

GET /api/v2/versions/?project_id=1 HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: localhost:5000
User-Agent: HTTPie/0.9.4

Example response:

HTTP/1.0 200 OK
Content-Length: 676
Content-Type: application/json
Date: Fri, 24 Mar 2017 18:44:32 GMT
Server: Werkzeug/0.12.1 Python/2.7.13

{
    "latest_version": "2.12",
    "versions": [
        "2.12",
        "2.11",
        "2.10",
        "2.9.1",
        "2.9",
        "2.8",
        "2.7"
    ],
    "stable_versions": [
        "2.12",
        "2.11",
        "2.10",
        "2.9.1",
        "2.9",
        "2.8",
        "2.7"
    ]
}
Query Parameters:
  • project_id (int) – The id of the project we want to get versions for.

Status Codes:
  • 200 OK – If all arguments are valid.

  • 400 Bad Request – If one or more of the query arguments is invalid.

  • 404 Not Found – If project with specified id doesn’t exist.

POST /api/v2/versions/

Check for new versions on the project. The API first checks if the project exists, if exists it will do check on it while applying any changes. If not it will create a temporary object in memory and do a check on the temporary object.

Example Request:

POST /api/v2/versions/ HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Authorization: token s12p01zUiVdEOZIhVf0jyZqtyYXfo2DECi6YdqqV
Connection: keep-alive
Content-Length: 15
Content-Type: application/json
Host: localhost:5000
User-Agent: HTTPie/1.0.3

{
    "id": "55612"
}

Example Response:

HTTP/1.0 200 OK
Content-Length: 118
Content-Type: application/json
Date: Tue, 20 Oct 2020 08:49:01 GMT
Server: Werkzeug/0.16.0 Python/3.8.6

{
    "found_versions": [],
    "latest_version": "0.0.2",
    "versions": [
        "0.0.2",
        "0.0.1"
    ],
    "stable_versions": [
        "0.0.2",
        "0.0.1"
    ]
}
Query Parameters:
  • access_token (string) – Your API access token.

Request JSON Object:
  • id (int) – Id of the project. If provided the check is done above existing project.

  • name (string) – The project name. Used as a filter to find existing project, if id not provided.

  • homepage (string) – The project homepage URL. Used as a filter to find existing project, if id not provided.

  • backend (string) – The project backend (github, folder, etc.).

  • version_url (string) – The URL to fetch when determining the project version.

  • version_scheme (string) – The project version scheme (defaults to “RPM” for temporary project).

  • version_pattern (string) – The version pattern for calendar version scheme.

  • version_prefix (string) – The project version prefix, if any.

  • pre_release_filter (string) – Filter for unstable versions.

  • version_filter (string) – Filter for blacklisted versions.

  • regex (string) – The regex to use when searching the version_url page (defaults to none for temporary project).

  • insecure (bool) – When retrieving the versions via HTTPS, do not validate the certificate (defaults to false for temporary project).

  • releases_only (bool) – When retrieving the versions, use releases instead of tags (defaults to false for temporary project). Only available for GitHub backend.

  • dry_run (bool) – If set, doesn’t save anything (defaults to true). Can’t be set to False for temporary project.

Status Codes:
  • 200 OK – When the versions were successfully retrieved.

  • 400 Bad Request – When required arguments are missing or malformed.

  • 401 Unauthorized – When your access token is missing or invalid, or when the server is not configured for OpenID Connect. The response will include a JSON body describing the exact problem.

  • 404 Not Found – When id is provided and the project doesn’t exist or is archived.

  • 500 Internal Server Error – If there is error during the check

HTTP API v1

GET /api
GET /api/

Retrieve the HTML information page.

Deprecated:

in Anitya 0.12 in favor of simple Sphinx documentation.

Status Codes:
  • 302 Found – A redirect to the HTML documentation.

GET /api/by_ecosystem/(ecosystem)/(project_name)
GET /api/by_ecosystem/(ecosystem)/(project_name)/

Retrieves a project in an ecosystem via the name of the ecosystem and the name of the project as registered with Anitya.

Parameters:
  • ecosystem (str) – the name of the ecosystem (case insensitive).

  • project_name (str) – the name of the project in Anitya.

Status Codes:
  • 200 OK – Returns the JSON representation of the project.

  • 404 Not Found – When either the ecosystem does not exist, or when there is no project with that name within the ecosystem.

Example request:

GET /api/by_ecosystem/pypi/six HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: release-monitoring.org
User-Agent: HTTPie/0.9.4

Example response:

HTTP/1.1 200 OK
Content-Length: 516
Content-Type: application/json

{
  "backend": "pypi",
  "created_on": 1409917222.0,
  "homepage": "https://pypi.python.org/pypi/six",
  "id": 2,
  "name": "six",
  "packages": [
    {
      "distro": "Fedora",
      "package_name": "python-six"
    }
  ],
  "regex": null,
  "updated_on": 1414400794.0,
  "version": "1.10.0",
  "version_url": null,
  "versions": [
    "1.10.0"
  ]
}
GET /api/distro/names
GET /api/distro/names/

Lists the names of all the distributions registered in anitya.

Query Parameters:
  • pattern – pattern to use to restrict the list of distributions returned.

Example request:

GET /api/distro/names/?pattern=F* HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: release-monitoring.org
User-Agent: HTTPie/0.9.4

Example response:

HTTP/1.1 200 OK
Content-Length: 79
Content-Type: application/json

{
    "distro": [
        "Fedora",
        "Fedora EPEL",
        "FZUG"
    ],
    "total": 3
}
GET /api/packages/wiki
GET /api/packages/wiki/

List all packages in mediawiki format.

Deprecated:

in Anitya 0.12 due to lack of pagination resulting in incredibly poor performance.

Lists all the packages registered in anitya using the format of the old wiki page. If a project is present multiple times on different distribution, it will be shown multiple times.

/api/packages/wiki

Accepts GET queries only.

Sample response:

* 2ping None https://www.finnie.org/software/2ping
* 3proxy None https://www.3proxy.ru/download/
GET /api/project/(distro)/(path: package_name)
GET /api/project/(distro)/(path: package_name)/

Retrieves a project in a distribution via the name of the distribution and the name of the package in said distribution.

/api/project/<distro>/<package_name>

Accepts GET queries only.

Parameters:
  • distro – the name of the distribution (case insensitive).

  • package_name – the name of the package in the distribution specified.

Sample response:

{
  "backend": "custom",
  "created_on": 1409917222.0,
  "homepage": "https://www.finnie.org/software/2ping/",
  "id": 2,
  "name": "2ping",
  "packages": [
    {
      "distro": "Fedora",
      "package_name": "2ping"
    }
  ],
  "regex": null,
  "updated_on": 1414400794.0,
  "version": "2.1.1",
  "version_url": "https://www.finnie.org/software/2ping",
  "versions": [
    "2.1.1"
  ]
}
GET /api/project/(int: project_id)
GET /api/project/(int: project_id)/

Retrieves a specific project using its identifier in anitya.

/api/project/<project_id>

Accepts GET queries only.

Parameters:
  • project_id – the identifier of the project in anitya.

Sample response:

{
  "backend": "custom",
  "created_on": 1409917222.0,
  "homepage": "https://www.finnie.org/software/2ping/",
  "id": 2,
  "name": "2ping",
  "packages": [
    {
      "distro": "Fedora",
      "package_name": "2ping"
    }
  ],
  "regex": null,
  "updated_on": 1414400794.0,
  "version": "2.1.1",
  "version_url": "https://www.finnie.org/software/2ping",
  "versions": [
    "2.1.1"
  ]
}
GET /api/projects
GET /api/projects/

Lists all the projects registered in Anitya.

This API accepts GET query strings:

/api/projects

/api/projects/?pattern=<pattern>

/api/projects/?pattern=py*

/api/projects/?homepage=<homepage>

/api/projects/?homepage=https%3A%2F%2Fpypi.python.org%2Fpypi%2Fansi2html

Accepts GET queries only.

Kwarg pattern:

pattern to use to restrict the list of projects returned.

Kwarg homepage:

upstream homepage to use to restrict the list of projects returned.

The pattern and homepage arguments are mutually exclusive and cannot be combined. You can query for packages by a pattern or you can query by their upstream homepage, but not both.

Sample response:

{
  "projects": [
    {
      "backend": "custom",
      "created_on": 1409917222.0,
      "homepage": "https://www.finnie.org/software/2ping/",
      "id": 2,
      "name": "2ping",
      "regex": null,
      "updated_on": 1414400794.0,
      "version": "2.1.1",
      "version_url": "https://www.finnie.org/software/2ping",
      "versions": [
        "2.1.1"
      ]
    },
    {
      "backend": "custom",
      "created_on": 1409917223.0,
      "homepage": "https://www.3proxy.ru/download/",
      "id": 3,
      "name": "3proxy",
      "regex": null,
      "updated_on": 1415115096.0,
      "version": "0.7.1.1",
      "version_url": "https://www.3proxy.ru/download/",
      "versions": [
        "0.7.1.1"
      ]
    }
  ],
  "total": 2
}
GET /api/projects/names
GET /api/projects/names/

Lists the names of all the projects registered in anitya.

Query Parameters:
  • pattern (str) – pattern to use to restrict the list of names returned.

Status Codes:
  • 200 OK – Returned in all cases.

Example request:

GET /api/projects/names?pattern=requests* HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: release-monitoring.org
User-Agent: HTTPie/0.9.4

Example response:

HTTP/1.1 200 OK
Content-Length: 248
Content-Type: application/json

{
    "projects": [
        "requests",
        "Requests",
        "requests-aws",
        "requestsexceptions",
        "requests-file",
        "requests-ftp",
        "requests-mock",
        "requests-ntlm",
        "requests-oauthlib",
        "requests-toolbelt"
    ],
    "total": 10
}
GET /api/version
GET /api/version/

Display the api version information.

/api/version

Accepts GET queries only.

Sample response:

{
  "version": "1.0"
}
POST /api/version/get

Forces anitya to retrieve new versions available from a project upstream.

/api/version/get

Accepts POST queries only.

Parameters:
  • id – the identifier of the project in anitya.

Sample response:

{
  "versions": [
    "2.7"
  ]
}

Sample error response:

{
  "output": "notok",
  "error": "Error happened."
}

Python APIs

Exceptions

Exceptions used by Anitya.

Authors:

Pierre-Yves Chibon <pingou@pingoured.fr>

exception anitya.lib.exceptions.AnityaException[source]

Bases: Exception

Generic class covering all the exceptions generated by anitya.

exception anitya.lib.exceptions.AnityaInvalidMappingException(pkgname, distro, found_pkgname, found_distro, project_id, project_name, link=None)[source]

Bases: AnityaException

Specific exception class for invalid mapping.

property message
exception anitya.lib.exceptions.AnityaPluginException[source]

Bases: AnityaException

Generic exception class that can be used by the plugin to indicate an error.

exception anitya.lib.exceptions.InvalidVersion(version, exception=None)[source]

Bases: AnityaException

Raised when the version string is not valid for the given version scheme.

Parameters:
  • version (str) – The version string that failed to parse.

  • exception (Exception) – The underlying exception that triggered this one.

exception anitya.lib.exceptions.ProjectExists(requested_project)[source]

Bases: AnityaException

Raised when a project already exists in the database.

This is only raised when a project is part of an ecosystem, since projects outside of an ecosystem have no uniqueness constraints.

to_dict()[source]
exception anitya.lib.exceptions.RateLimitException(reset_time)[source]

Bases: AnityaException

Raised when the rate limit for requests is reached.

reset_time

Time when limit will be reset.

Type:

arrow.Arrow

Database API

This package contains all the database-related code, including SQLAlchemy models, Alembic migrations, and a scoped session object configured from anitya.config

anitya.db.meta

This module sets up the basic database objects that all our other modules will rely on. This includes the declarative base class and global scoped session.

This is in its own module to avoid circular imports from forming. Models and events need to be imported by __init__.py, but they also need access to the Base model and Session.

class anitya.db.meta.Base(**kwargs: Any)

Bases: _AnityaBase

Base class for the SQLAlchemy model base class.

query

a class property which produces a BaseQuery object against the class and the current Session when called. Classes that want a customized Query class should sub-class BaseQuery and explicitly set the query property on the model.

Type:

sqlalchemy.orm.query.Query

metadata = MetaData()
registry = <sqlalchemy.orm.decl_api.registry object>
class anitya.db.meta.BaseQuery(entities: _ColumnsClauseArgument[Any] | Sequence[_ColumnsClauseArgument[Any]], session: Session | None = None)[source]

Bases: Query

A base Query object that provides queries.

paginate(page=None, items_per_page=None, order_by=None)[source]

Retrieve a page of items.

Parameters:
  • page (int) – the page number to retrieve. This page is 1-indexed and defaults to 1.

  • items_per_page (int) – The number of items per page. This defaults to 25.

  • order_by (sa.Column or tuple) – One or more criterion by which to order the pages.

Returns:

A namedtuple of the items.

Return type:

Page

Raises:

ValueError – If the page or items_per_page values are less than 1.

class anitya.db.meta.Page(items, page, items_per_page, total_items)[source]

Bases: _Page

A sub-class of namedtuple that represents a page.

items

The database objects from the query.

Type:

object

page

The page number used for the query.

Type:

int

items_per_page

The number of items per page.

Type:

int

total_items

The total number of items in the database.

Type:

int

as_dict()[source]

Return a dictionary representing the page.

Returns:

A dictionary representation of the page and its items, using

the __json__ method defined on the item objects.

Return type:

dict

anitya.db.meta.Session = <sqlalchemy.orm.scoping.scoped_session object>

This is a configured scoped session. It creates thread-local sessions. This means that Session() is Session() is True. This is a convenient way to avoid passing a session instance around. Consult SQLAlchemy’s documentation for details.

Before you can use this, you must call initialize().

anitya.db.meta.initialize(config)[source]

Initialize the database.

This creates a database engine from the provided configuration and configures the scoped session to use the engine.

Parameters:

config (dict) – A dictionary that contains the configuration necessary to initialize the database.

Returns:

The database engine created from the configuration.

Return type:

sqlalchemy.engine

anitya.db.events

This module contains functions that are triggered by SQLAlchemy events.

anitya.db.events.set_ecosystem_backend(target, value, old, initiator)[source]

An SQLAlchemy event listener that sets the ecosystem for a project if backend is changed.

Parameters:
  • target (sqlalchemy.orm.state.InstanceStace) – Instance of the object where change is happening.

  • value (str) – The new value of backend.

  • old (str) – The old value of backend.

  • initiator (sqlalchemy.orm.attributes.Event) – The event object that is initiating this transition.

anitya.db.events.set_ecosystem_homepage(target, value, old, initiator)[source]

An SQLAlchemy event listener that sets the ecosystem for a project if homepage is changed.

Parameters:
  • target (sqlalchemy.orm.state.InstanceStace) – Instance of the object where change is happening.

  • value (str) – The new value of homepage.

  • old (str) – The old value of homepage.

  • initiator (sqlalchemy.orm.attributes.Event) – The event object that is initiating this transition.

anitya.db.models

SQLAlchemy database models.

class anitya.db.models.ApiToken(**kwargs)[source]

Bases: Base

A table for user API tokens.

token

A 40 character string that represents the API token. This is the primary key and is, by default, generated automatically.

Type:

sa.String

created

The time this API token was created.

Type:

sa.DateTime

description

A user-provided description of what the API token is for.

Type:

sa.Text

user

The user this API token is associated with.

Type:

User

created
description
token
user
user_id
class anitya.db.models.Distro(name)[source]

Bases: Base

Class Distro

classmethod all(session, page=None, count=False)[source]

Distro all

classmethod by_name(session, name)[source]

Get Distro name

classmethod get(session, name)

Get Distro name

classmethod get_or_create(session, name)[source]

Get distro or create it

name
package
classmethod search(session, pattern, page=None, count=False)[source]

Search the distribuutions by their name

class anitya.db.models.GUID(*args: Any, **kwargs: Any)[source]

Bases: TypeDecorator

Platform-independent GUID type.

If PostgreSQL is being used, use its native UUID type, otherwise use a CHAR(32) type.

impl

alias of CHAR

load_dialect_impl(dialect)[source]

PostgreSQL has a native UUID type, so use it if we’re using PostgreSQL.

Parameters:

dialect (sqlalchemy.engine.interfaces.Dialect) – The dialect in use.

Returns:

Either a PostgreSQL UUID or a CHAR(32) on other

dialects.

Return type:

sqlalchemy.types.TypeEngine

process_bind_param(value, dialect)[source]

Process the value being bound.

If PostgreSQL is in use, just use the string representation of the UUID. Otherwise, use the integer as a hex-encoded string.

Parameters:
Returns:

The value of the UUID as a string.

Return type:

str

process_literal_param(value, dialect)[source]

Receive a literal parameter value to be rendered inline within a statement.

Note

This method is called during the SQL compilation phase of a statement, when rendering a SQL string. Unlike other SQL compilation methods, it is passed a specific Python value to be rendered as a string. However it should not be confused with the _types.TypeDecorator.process_bind_param() method, which is the more typical method that processes the actual value passed to a particular parameter at statement execution time.

Custom subclasses of _types.TypeDecorator should override this method to provide custom behaviors for incoming data values that are in the special case of being rendered as literals.

The returned string will be rendered into the output string.

process_result_value(value, dialect)[source]

Casts the UUID value to the native Python type.

Parameters:
Returns:

The value as a Python uuid.UUID.

Return type:

uuid.UUID

class anitya.db.models.Packages(**kwargs)[source]

Bases: Base

Class Packages

classmethod by_id(session, pkg_id)[source]

Packages by id

classmethod by_package_name_distro(session, package_name, distro_name)[source]

Get package by package name distro

distro
distro_name
classmethod get(session, project_id, distro_name, package_name)[source]

Get Packages

id
package_name
project
project_id
class anitya.db.models.Project(**kwargs)[source]

Bases: Base

Models an upstream project and maps it to a database table.

id

The database primary key.

Type:

sa.Integer

name

The upstream project’s name.

Type:

sa.String

homepage

The URL for the project’s home page.

Type:

sa.String

backend

The name of the backend to use when fetching updates; this is a foreign key to a Backend.

Type:

sa.String

ecosystem_name

The name of the ecosystem this project is a part of. If the project isn’t part of an ecosystem (e.g. PyPI), use the homepage URL.

Type:

sa.String

version_url

The url to use when polling for new versions. This may be ignored if this project is part of an ecosystem with a fixed URL (e.g. Cargo projects are on https://crates.io).

Type:

sa.String

regex

A Python re style regular expression that is applied to the HTML from version_url to find versions.

Type:

sa.String

version_prefix

A string containing version prefixes delimited by ‘;’. These prefixes will be removed from string showed on page.

Type:

sa.String

version_pattern

A version pattern used for calendar version scheme.

Type:

sa.String

insecure

Whether or not to validate the x509 certificate offered by the server at version_url. Defaults to False.

Type:

sa.Boolean

releases_only

Whether or not to check releases instead of tags. This is now only used by GitHub backend.

Type:

sa.Boolean

error_counter

Counter that contains number of unsuccessful checks. This counter will reset each time a successful check is done. Doesn’t count ratelimit errors.

Type:

sa.Integer

latest_version

The latest version for the project, as determined by the version sorting algorithm.

Type:

sa.String

logs

The result of the last update.

Type:

sa.Text

check_successful

Flag that contains result of last check. None - not checked yet, True - checked successfully, False - error occured during check

Type:

sa.Boolean

updated_on

When the project was last updated.

Type:

sa.DateTime

created_on

When the project was created in Anitya.

Type:

sa.DateTime

packages

List of Package objects which represent the downstream packages for this project.

Type:

list

version_scheme

The version scheme to use for this project. If this is null, a default will be used. See the anitya.lib.versions documentation for more information.

Type:

sa.String

pre_release_filter

A string containing filters delimited by ‘;’. Filtered versions will be marked as pre_release.

Type:

sa.String

archived

Marks the project as archived, archived projects can’t be edited by normal users and are no longer checked for new versions.

Type:

sa.Boolean

version_filter

A string containing filters delimited by ‘;’. Filtered versions will be skipped when retrieving versions.

Type:

sa.String

classmethod all(session, page=None, count=False)[source]
archived
backend
classmethod by_distro(session, distro, page=None, count=False)[source]

By distro

classmethod by_homepage(session, homepage)[source]

By homepage

classmethod by_id(session, project_id)[source]

By id

classmethod by_name(session, name)[source]

By name

classmethod by_name_and_ecosystem(session, name, ecosystem)[source]

By name and ecosystem

classmethod by_name_and_homepage(session, name, homepage)[source]

By name and homepage

check_successful
create_version_objects(versions)[source]

Creates sorted list of version objects defined by self.version_class from versions list.

Parameters:

versions (list(str or dict)) – List of versions that are not associated with the project.

Returns:

List of version objects defined by

self.version_class.

Return type:

list(anitya.lib.versions.Base)

created_on
ecosystem_name
error_counter
flags
classmethod get(session, project_id)

By id

get_last_created_version()[source]

Returns last obtained release by date.

Returns:

Version object or None, if project doesn’t have any version yet.

Return type:

(ProjectVersion)

classmethod get_or_create(session, name, homepage, backend='custom')[source]

Get or Create

get_sorted_version_objects()[source]

Return list of all version objects stored, sorted from newest to oldest.

Returns:

List of version objects

Return type:

list of anitya.lib.versions.Base

get_time_last_created_version()[source]

Returns creation time of latest version sorted by time of creation.

Returns:

Time of the latest created version or None,

if project doesn’t have any version yet.

Return type:

(arrow.Arrow)

get_version_class()[source]

Get the class for the version scheme used by this project.

This will take into account the defaults set in the ecosystem, backend, and globally. The version scheme locations are checked in the following order and the first non-null result is returned:

  1. On the project itself in the version_scheme column.

  2. The project’s ecosystem default, if the project is part of one.

  3. The project’s backend default, if the backend defines one.

  4. The global default defined in anitya.lib.versions.GLOBAL_DEFAULT

Returns:

A Version sub-class.

Return type:

anitya.lib.versions.Version

get_version_url()[source]

Returns full version url, which is used by backend.

Returns:

Version url or empty string if backend is not specified

Return type:

str

homepage
id
insecure
last_check
property latest_stable_version

Return latest stable version.

Returns:

Latest stable version if exists, otherwise None.

Return type:

string

latest_version
property latest_version_object

Latest version object

logs
name
next_check
package
packages
pre_release_filter
regex
releases_only
classmethod search(session, pattern, distro=None, page=None, count=False)[source]

Search the projects by their name or package name

classmethod sort_projects(projects, sort)[source]

Sorts a list of projects objects based on a sort parameter.

property stable_versions

Return list of all versions that aren’t flagged as pre-release.

Returns:

List of stable version objects

Return type:

list(anitya.lib.versions.Base)

classmethod updated(session, status='updated', name=None, log=None, page=None, count=False)[source]

Method used to retrieve projects according to their logs and how they performed at the last cron job.

Keyword Arguments:
  • status – used to filter the projects based on how they performed at the last cron run

  • name – if present, will return the entries having the matching name

  • log – if present, will return the entries having the matching log

  • page – The page number of returned, pages contain 50 entries

  • count – A boolean used to return either the list of entries matching the criterias or just the COUNT of entries

updated_on
validate_backend(key, value)[source]

Validate backend

version_filter
version_pattern
version_prefix
version_scheme
version_url
property versions

Return list of all versions stored, sorted from newest to oldest.

Returns:

List of versions

Return type:

list of str

versions_obj
class anitya.db.models.ProjectFlag(**kwargs)[source]

Bases: Base

Class ProjectFlag

classmethod all(session, page=None, count=False)[source]
created_on
classmethod get(session, flag_id)[source]
id
project
project_id
reason
classmethod search(session, project_name=None, from_date=None, user=None, state=None, limit=None, offset=None, count=False)[source]

Return the list of the last Flag entries present in the database.

Parameters:
  • cls – the class object

  • session – the database session used to query the information.

Keyword Arguments:
  • project_name – the name of the project to restrict the flags to.

  • from_date – the date from which to give the entries.

  • user – the name of the user to restrict the flags to.

  • state – the flag’s status (open or closed).

  • limit – limit the result to X rows.

  • offset – start the result at row X.

  • count – a boolean to return the result of a COUNT query if true, returns the data if false (default).

state
updated_on
user
class anitya.db.models.ProjectVersion(**kwargs)[source]

Bases: Base

Models of version table representing version on project.

project_id

Related project id.

Type:

sa.Integer

version

Raw version string as obtained from upstream.

Type:

sa.String

created_on

When the version was created in Anitya.

Type:

sa.DateTime

commit_url

URL to commit. Currently only used by GitHub backend.

Type:

sa.String

project

Back reference to project.

Type:

sa.orm.relationship

commit_url
created_on
property pre_release

Is the version pre-release?

Returns:

Pre-release flag.

Return type:

(Boolean)

project
project_id
version
class anitya.db.models.Run(**kwargs)[source]

Bases: Base

Class Run

created_on
error_count
classmethod last_entry(session)[source]

Return the last log about the cron run.

ratelimit_count
success_count
total_count
class anitya.db.models.User(**kwargs)[source]

Bases: Base

A table for Anitya users.

This table is intended to work with a table of third-party authentication providers. Anitya does not support local users.

id

The primary key for the table.

Type:

uuid.UUID

email

The user’s email.

Type:

str

username

The user’s username, as retrieved from third-party authentication.

Type:

str

active

Indicates whether the user is active. If false, users will not be able to log in.

Type:

bool

admin

Determine if this user is an administrator. If True the user is administrator.

Type:

bool

social_auth

The list of social_flask_sqlalchemy.models.UserSocialAuth entries for this user.

Type:

sqlalchemy.orm.dynamic.AppenderQuery

active
admin
api_tokens
email
get_id()[source]

Implement the flask-login interface for retrieving the user’s ID.

Returns:

The Unicode string that uniquely identifies a user.

Return type:

six.text_type

id
property is_active

Implement the flask-login interface for determining if the user is active.

If a user is _not_ active, they are not allowed to log in.

Returns:

True if the user is active.

Return type:

bool

property is_admin

Determine if this user is an administrator. Set admin flag if the user is preconfigured.

Returns:

True if the user is an administrator.

Return type:

bool

property is_anonymous

Implement the flask-login interface for determining if the user is authenticated.

flask-login uses an “anonymous user” object if there is no authenticated user. This indicates to flask-login this user is not an anonymous user.

Returns:

False in all cases.

Return type:

bool

property is_authenticated

Implement the flask-login interface for determining if the user is authenticated.

In this case, if flask-login has an instance of User, then that user has already authenticated via a third-party authentication mechanism.

Returns:

True in all cases.

Return type:

bool

to_dict()[source]

Creates json compatible dict from User.

Returns:

User object transformed to dictionary.

Return type:

dict

username

Backend API

The Anitya backends API.

class anitya.lib.backends.BaseBackend[source]

Bases: object

The base class that all the different backends should extend.

name

The backend name. This is displayed to the user and used in URLs.

Type:

str

examples

A list of strings that are displayed to the user to indicate example project URLs.

Type:

list

default_regex

A regular expression to use by default with the backend.

Type:

str

more_info

A string that provides more detailed information to the user about the backend.

Type:

str

default_version_scheme

The default version scheme for this backend. This is only used if both the project and the ecosystem the project is a part of do not define a default version scheme. If this is not defined, anitya.lib.versions.GLOBAL_DEFAULT is used.

Type:

str

check_interval

Interval which is used for periodic checking for new versions. This could be overriden by backend plugin.

Type:

datetime.timedelta

classmethod call_url(url, last_change=None, insecure=False)[source]

Dedicated method to query a URL.

It is important to use this method as it allows to query them with a defined user-agent header thus informing the projects we are querying what our intentions are.

To prevent downloading the whole content of the page each time the url is called. We are using If-modified-since header field.

url

The url to request (get).

Type:

str

last_change

Time when the latest version was obtained. This value is used in If-modified-since header field. If there is no value provided we will use start of the epoch (1.1. 1970).

Type:

arrow.Arrow, optional

insecure

Flag for secure/insecure connection. Defaults to False.

Type:

bool, optional

Returns:

In case of FTP url it returns binary encoded string otherwise requests.Response object.

classmethod check_feed()[source]

Method called to retrieve the latest uploads to a given backend, via, for example, RSS or an API.

Not all backends may support this. It can be used to look for updates much more quickly than scanning all known projects.

Returns:

A list of 4-tuples, containing the project name, homepage, the backend, and the version.

Return type:

list

Raises:
check_interval = datetime.timedelta(seconds=3600)
default_regex: str
default_version_scheme = 'RPM'
examples: List[str]
classmethod expand_subdirs(url, last_change=None, glob_char='*')[source]

Expand dirs containing glob_char in the given URL with the latest Example URL: https://www.example.com/foo/*/

The globbing char can be bundled with other characters enclosed within the same slashes in the URL like /rel*/.

Code originally from Till Maas as part of cnucnu

classmethod filter_versions(versions, filter_string)[source]

Method called to filter versions list by filter_string. Filter string is first parsed by delimiter and then applied on list of versions. For example: list of versions [“1.0.0”, “1.0.0-alpha”, “1.0.0-beta”] when filtered by “alpha;beta” will return [“1.0.0”].

versions

List of versions. For example [“1.0.0, 1.0.0-alpha”]

Type:

list

filter_string

String to use for filtering. It contains list of strings delimited by “;”.

Type:

str

Returns:

A list of filtered versions.

Return type:

list

classmethod get_ordered_versions(project)[source]

Method called to retrieve all the versions (that can be found) of the projects provided, ordered from the oldest to the newest.

project

Project object whose backend corresponds to the current plugin.

Type:

anitya.db.models.Project

Returns:

A sorted list of all the possible releases found

Return type:

list

Raises:

AnityaPluginException – A anitya.lib.exceptions.AnityaPluginException exception when the versions cannot be retrieved correctly

classmethod get_version(project)[source]

Method called to retrieve the latest version of the projects provided, project that relies on the backend of this plugin.

project

Project object whose backend corresponds to the current plugin.

Type:

anitya.db.models.Project

Returns:

Latest version found upstream

Return type:

str

Raises:

AnityaPluginException – A anitya.lib.exceptions.AnityaPluginException exception when the versions cannot be retrieved correctly

classmethod get_version_url(project)[source]

Method called to retrieve the url used to check for new version of the project provided, project that relies on the backend of this plugin.

project

Project object whose backend corresponds to the current plugin.

Type:

anitya.db.models.Project

Returns:

url used for version checking

Return type:

str

classmethod get_versions(project)[source]

Method called to retrieve all the versions (that can be found) of the projects provided, project that relies on the backend of this plugin.

project

Project object whose backend corresponds to the current plugin.

Type:

anitya.db.models.Project

Returns:

A list of all the possible releases found. The items

in the list can either be strings of versions or dictionaries containing at minimum the version (in a version key).

Return type:

list

Raises:

AnityaPluginException – A anitya.lib.exceptions.AnityaPluginException exception when the versions cannot be retrieved correctly

more_info: str
name: str
anitya.lib.backends.get_versions_by_regex(url, regex, project, insecure=False)[source]

For the provided url, return all the version retrieved via the specified regular expression.

anitya.lib.backends.get_versions_by_regex_for_text(text, url, regex, project)[source]

For the provided text, return all the version retrieved via the specified regular expression.

Plugin API

Module handling the load/call of the plugins of anitya.

anitya.lib.plugins.get_plugin(plugin_name)

Return the plugin corresponding to the given plugin name.

anitya.lib.plugins.get_plugin_names()

Return the list of plugin names.

anitya.lib.plugins.get_plugins()

Return the list of plugins.

anitya.lib.plugins.load_all_plugins(session)[source]

Load all the plugins and insert them in the database if they are not already present.

anitya.lib.plugins.load_plugins(session, family='backends')[source]

Calls load_all_plugins, but only retuns plugins specified by family argument

Parameters:

family (str) – family of the plugins, that should be returned

Ecosystem API

The Anitya ecosystems API.

Authors:

Nick Coghlan <ncoghlan@redhat.com>

class anitya.lib.ecosystems.BaseEcosystem[source]

Bases: object

The base class that all the different ecosystems should extend.

name

The ecosystem name. This name is used to associate projects with an ecosystem and is user-facing. It is also used in URLs.

Type:

str

default_backend

The default backend to use for projects in this ecosystem if they don’t explicitly define one to use.

Type:

str

default_version_scheme

The default version scheme to use for projects in this ecosystem if a they don’t explicitly define one to use.

Type:

str

aliases

A list of alternate names for this ecosystem. These should be lowercase.

Type:

list

aliases: List[str] = []
default_backend: str
default_version_scheme: str = 'RPM'
name: str

Versions API

The Anitya versions API.

class anitya.lib.versions.base.Version(version: str | None = None, prefix: str | None = None, created_on: datetime | None = None, pattern: str | None = None, cursor: str | None = None, commit_url: str | None = None, pre_release_filter: str | None = None)[source]

Bases: object

The base class for versions.

name = 'Generic Version'
newer(other_versions)[source]

Check a version against a list of other versions to see if it’s newer.

Example

>>> version = Version(version='1.1.0')
>>> version.newer([Version(version='1.0.0')])
True
>>> version.newer(['1.0.0', '0.0.1'])  # You can pass strings!
True
>>> version.newer(['1.2.0', '2.0.1'])
False
Parameters:

other_versions (list) – A list of version strings or Version objects to check the version string against.

Returns:

True if self is the newest version, False otherwise.

Return type:

bool

Raises:

InvalidVersion – if one or more of the version strings provided cannot be parsed.

parse()[source]

Parse the version string to an object representing the version.

This does some minimal string processing, stripping any prefix set on project.

Returns:

The version string. Sub-classes may return a different type. object: Sub-classes may return a special class that represents the version. This must support comparison operations and return a parsed, prefix-stripped version when __str__ is invoked.

Return type:

str

Raises:

InvalidVersion – If the version cannot be parsed.

postrelease()[source]

Check if a version is a post-release version.

This basic version implementation does not have a concept of post-releases.

prerelease() bool[source]

Check if a version is a pre-release version.

This basic version implementation does not have a concept of pre-releases.

anitya.lib.versions.base.v_prefix = re.compile('v\\d.*')

A regular expression to determine if the version string contains a ‘v’ prefix.