# API Documentation

Anitya provides several APIs for users.

## HTTP API v2

`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

    - Authorization – API token to use for authentication

  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

    - 201 Created – When the package was successfully created.

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

    - 401 Unauthorized – When your access token is missing or invalid

    - 409 Conflict – When the package already exists.

`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",
              }
          ],
          "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/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": []
      }

  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_prefix (string) – The project version prefix, if any. For example, some projects prefix with “v”.

    - 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/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"
                  ]
              }
          ],
          "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.

## 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 the latest version available from a project upstream.

      /api/version/get

  Accepts POST queries only.

  Parameters

    - id – the identifier of the project in anitya.

  Sample response:

      {
        "backend": "Sourceforge",
        "created_on": 1409917222.0,
        "homepage": "https://sourceforge.net/projects/zero-install",
        "id": 1,
        "name": "zero-install",
        "packages": [
          {
            "distro": "Fedora",
            "package_name": "0install"
          }
        ],
        "regex": "",
        "updated_on": 1413794215.0,
        "version": "2.7",
        "version_url": "0install",
        "versions": [
          "2.7"
        ]
      }

## Python APIs

Anitya can be used without its web front-end, if you so choose. Please be aware that Anitya is still in the early stages of development and its Python APIs are not stable.

### Exceptions

Exceptions used by Anitya.

Authors:

  Pierre-Yves Chibon <pingou@pingoured.fr>

exception `anitya.lib.exceptions.``AnityaException`

  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)

  Bases: `anitya.lib.exceptions.AnityaException`

  Specific exception class for invalid mapping.

  property `message`

exception `anitya.lib.exceptions.``AnityaPluginException`

  Bases: `anitya.lib.exceptions.AnityaException`

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

exception `anitya.lib.exceptions.``InvalidVersion`(version, exception=None)

  Bases: `anitya.lib.exceptions.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)

  Bases: `anitya.lib.exceptions.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`()

exception `anitya.lib.exceptions.``RateLimitException`(reset_time)

  Bases: `anitya.lib.exceptions.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)

  Bases: `anitya.db.meta._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(bind=None)

class `anitya.db.meta.``BaseQuery`(entities, session=None)

  Bases: `sqlalchemy.orm.query.Query`

  A base Query object that provides queries.

  `paginate`(page=None, items_per_page=None, order_by=None)

    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`

  Bases: `anitya.db.meta._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`()

    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)

  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`(session, flush_context, instances)

  An SQLAlchemy event listener that sets the ecosystem for a project if it’s null.

  Parameters

    - session (sqlalchemy.orm.session.Session) – The session that is about to be committed.

    - flush_context (sqlalchemy.orm.session.UOWTransaction) – Unused.

    - instances (object) – deprecated and unused

  Raises

    ValueError – If the ecosystem_name isn’t valid.

#### anitya.db.models

SQLAlchemy database models.

class `anitya.db.models.``ApiToken`(**kwargs)

  Bases: `sqlalchemy.ext.declarative.api.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)

  Bases: `sqlalchemy.ext.declarative.api.Base`

  classmethod `all`(session, page=None, count=False)
  classmethod `by_name`(session, name)
  classmethod `get`(session, name)
  classmethod `get_or_create`(session, name)
  `name`
  `package`
  classmethod `search`(session, pattern, page=None, count=False)

    Search the distribuutions by their name

class `anitya.db.models.``GUID`(*args, **kwargs)

  Bases: `sqlalchemy.sql.type_api.TypeDecorator`

  Platform-independent GUID type.

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

  `impl`

    alias of `sqlalchemy.sql.sqltypes.CHAR`

  `load_dialect_impl`(dialect)

    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)

    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

      - value (object) – The value that’s being bound to the object.

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

    Returns

      The value of the UUID as a string.

    Return type

      str

  `process_result_value`(value, dialect)

    Casts the UUID value to the native Python type.

    Parameters

      - value (object) – The database value.

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

    Returns

      The value as a Python `uuid.UUID`.

    Return type

      uuid.UUID

class `anitya.db.models.``Packages`(**kwargs)

  Bases: `sqlalchemy.ext.declarative.api.Base`

  classmethod `by_id`(session, pkg_id)
  classmethod `by_package_name_distro`(session, package_name, distro_name)
  `distro`
  `distro_name`
  classmethod `get`(session, project_id, distro_name, package_name)
  `id`
  `package_name`
  `project`
  `project_id`

class `anitya.db.models.``Project`(**kwargs)

  Bases: `sqlalchemy.ext.declarative.api.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

  `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

  `latest_version`

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

    Type

      sa.Boolean

  `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

  classmethod `all`(session, page=None, count=False)
  `backend`
  classmethod `by_distro`(session, distro, page=None, count=False)
  classmethod `by_homepage`(session, homepage)
  classmethod `by_id`(session, project_id)
  classmethod `by_name`(session, name)
  classmethod `by_name_and_ecosystem`(session, name, ecosystem)
  classmethod `by_name_and_homepage`(session, name, homepage)
  `check_successful`
  `create_version_objects`(versions)

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

    Parameters

      versions (list(str)) – 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`
  `flags`
  classmethod `get`(session, project_id)
  `get_last_created_version`()

    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')
  `get_sorted_version_objects`()

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

    Returns

      List of version objects

    Return type

      `list` of `anitya.db.models.ProjectVersion`

  `get_time_last_created_version`()

    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`()

    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`()

    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`
  `latest_version`
  `logs`
  `name`
  `next_check`
  `package`
  `packages`
  `regex`
  `releases_only`
  classmethod `search`(session, pattern, distro=None, page=None, count=False)

    Search the projects by their name or package name

  classmethod `updated`(session, status='updated', name=None, log=None, page=None, count=False)

    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)
  `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)

  Bases: `sqlalchemy.ext.declarative.api.Base`

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

    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)

  Bases: `sqlalchemy.ext.declarative.api.Base`

  `created_on`
  `project`
  `project_id`
  `version`

class `anitya.db.models.``Run`(**kwargs)

  Bases: `sqlalchemy.ext.declarative.api.Base`

  `created_on`
  `error_count`
  classmethod `last_entry`(session)

    Return the last log about the cron run.

  `ratelimit_count`
  `success_count`
  `total_count`

class `anitya.db.models.``User`(**kwargs)

  Bases: `sqlalchemy.ext.declarative.api.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`()

    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

  `social_auth`
  `to_dict`()

    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`

  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)

    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`()

    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

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

      - NotImplementedError – If backend does not support batch updates.

  `check_interval` = datetime.timedelta(seconds=3600)
  `default_regex` = None
  `default_version_scheme` = None
  `examples` = None
  classmethod `expand_subdirs`(url, last_change=None, glob_char='*')

    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 `get_ordered_versions`(project)

    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)

    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)

    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)

    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

    Return type

      `list`

    Raises

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

  `more_info` = None
  `name` = None

`anitya.lib.backends.``get_versions_by_regex`(url, regex, project, insecure=False)

  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)

  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)

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

`anitya.lib.plugins.``load_plugins`(session, family='backends')

  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`

  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` = []
  `default_backend` = None
  `default_version_scheme` = None
  `name` = None

### Versions API

The Anitya versions API.

class `anitya.lib.versions.base.``Version`(version: Optional[str] = None, prefix: Optional[str] = None, created_on: Optional[datetime.datetime] = None, pattern: Optional[str] = None)

  Bases: `object`

  The base class for versions.

  `name` = 'Generic Version'
  `newer`(other_versions)

    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`()

    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`()

    Check if a version is a post-release version.

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

  `prerelease`()

    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.