Topics

#api #artifactory #jfrog #pydantic #python #python-library #python-types #python3

Language breakdown

Python 100.0%

▸ Files click to expand

README

PyArtifactory

pyartifactory is a Python library to access the Artifactory REST API.

This library enables you to manage Artifactory resources such as users, groups, permissions, repositories, artifacts and access tokens in your applications. Based on Python 3.8+ type hints.

Requirements
Install
Usage

* Authentication + Basic authentication + Authentication with access token * SSL Cert Verification Options * Timeout option * Admin objects + User + Group + Security + Repository + Permission - Artifactory lower than 6.6.0 - Artifactory 6.6.0 or higher * Artifacts + Get the information about a file or folder + Deploy an artifact + Deploy an artifact with properties + Deploy an artifact by checksums + Download an artifact + Retrieve artifact list + Retrieve artifact properties + Set artifact properties + Update artifact properties + Retrieve artifact stats + Copy artifact to a new location + Move artifact to a new location + Delete an artifact * Builds + Get a list of all builds + Get a list of build runs + Get the information about a build + Create build + Promote a build + Delete one or more builds + Delete all build numbers of a build + Rename a build + Get differences between two builds * Contributing

Requirements

Python 3.8+

Install

pip install pyartifactory

Usage

Authentication

Since Artifactory 6.6.0 there is version 2 of the REST API for permission management, in case you have that version or higher, you need to pass api_version=2 to the constructor when you instantiate the class.

Basic authentication

from pyartifactory import Artifactory
art = Artifactory(url="ARTIFACTORYURL", auth=('USERNAME','PASSWORDORAPIKEY'), api_version=1)

Authentication with access token

from pyartifactory import Artifactory
art = Artifactory(url="ARTIFACTORYURL", accesstoken="your-access-token")

Note:

If you set both accesstoken and auth, the accesstoken authentication will be chosen
If you do not set any authentication method, API calls will be done without authentication (anonymous)

SSL Cert Verification Options

Specify a local cert to use as client side certificate

from pyartifactory import Artifactory
art = Artifactory(url="ARTIFACTORYURL", auth=('USERNAME','PASSWORDORAPIKEY'), cert="/pathtofile/server.pem", api_version=1)

Specify a local cert to use as custom CA certificate

from pyartifactory import Artifactory
art = Artifactory(url="ARTIFACTORYURL", auth=('USERNAME','PASSWORDORAPIKEY'), verify="/pathtofile/ca.pem", cert="/pathtofile/server.pem", api_version=1)

verify and cert configure certificates for distinct purposes. verify determines SSL/TLS certificate validation for the server, while cert supplies a client certificate for mutual authentication, as required by the server. You can use either one or both parameters as needed.

Disable host cert verification

from pyartifactory import Artifactory
art = Artifactory(url="ARTIFACTORYURL", auth=('USERNAME','PASSWORDORAPIKEY'), verify=False, api_version=1)

verify can be also set as a boolean to enable/disable SSL host verification.

Timeout option

Use timeout option to limit connect and read timeout in case the artifactory server is not responding in a timely manner.

from pyartifactory import Artifactory
art = Artifactory(url="ARTIFACTORYURL", auth=('USERNAME','PASSWORDORAPIKEY'), api_version=1, timeout=60)

timeout is None by default.

Admin objects

User

First, you need to create a new Artifactory object.

from pyartifactory import Artifactory art = Artifactory(url="ARTIFACTORYURL", auth=('USERNAME','PASSWORDORAPIKEY'))

Get the list of users:

users = art.users.list()

Get a single user:

user = art.users.get("test_user")

Create a user:

from pyartifactory.models import NewUser
Create User
user = NewUser(name="testuser", password="testpassword", email="user@user.com")
new_user = art.users.create(user)
Update user
user.email = "test@test.com"
updated_user = art.users.update(user)

Update a user:

from pyartifactory.models import User
user = art.users.get("test_user")
Update user
user.email = "test@test.com"
updated_user = art.users.update(user)

Delete a user:

art.users.delete("test_user")

Unlock a user:

art.users.unlock("test_user")

Group

Get the list of groups:

groups = art.groups.list()

Get a single group:

group = art.groups.get("group_name")

Create/Update a group:

from pyartifactory.models import Group
Create a Group
group = Group(name="testgroup", description="testgroup")
new_group = art.groups.create(group)
Update a Group
group.description = "testgroup2"
updated_group = art.groups.update(group)

Delete a group:

art.groups.delete("test_group")

Security

A set of methods for performing operations on apiKeys, passwords ...

>>> art.security. art.security.createapikey(          art.security.getencryptedpassword(  art.security.revokeapikey( art.security.getapikey(             art.security.regenerateapikey(      art.security.revokeuserapi_key(

Create an access token:

token = art.security.createaccesstoken(username='artifactoryuser', refreshable=True, scope="applied-permissions/user")

Revoke an existing revocable token:

art.security.revokeaccesstoken(token.access_token)

Repository

Get the list of repositories:

repositories = art.repositories.list()

Get a single repository

repo = art.repositories.getrepo("reponame") According to the repo type, you'll have either a local, virtual or remote repository returned

Create/Update a repository:

from pyartifactory.models import (     LocalRepository,     VirtualRepository,     RemoteRepository,     FederatedRepository )
Create local repo
localrepo = LocalRepository(key="testlocal_repo")
newlocalrepo = art.repositories.createrepo(localrepo)
Create virtual repo
virtualrepo = VirtualRepository(key="testvirtual_repo")
newvirtualrepo = art.repositories.createrepo(virtualrepo)
Create remote repo
remoterepo = RemoteRepository(key="testremote_repo", url="http://test-url.com")
newremoterepo = art.repositories.createrepo(remoterepo)
Create federated repo
remoterepo = FederatedRepository(key="testremote_repo")
newfederatedrepo = art.repositories.createrepo(remoterepo)
Update a repository
localrepo = art.repositories.getrepo("testlocalrepo")
localrepo.description = "testlocal_repo"
updatedlocalrepo = art.repositories.updaterepo(localrepo)

Delete a repository:

art.repositories.delete("testlocalrepo")

Permission

Get the list of permissions:

permissions = art.permissions.list()

Get a single permission:

users = art.permissions.get("test_permission")

Create/Update a permission:

Artifactory lower than 6.6.0

from pyartifactory.models import Permission
Create a permission
permission = Permission(
    **{
        "name": "test_permission",
        "repositories": ["test_repository"],
        "principals": {
            "users": {"test_user": ["r", "w", "n", "d"]},
            "groups": {"developers": ["r"]},
        },
    }
)
perm = art.permissions.create(permission)
Update permission
permission.repositories = ["testrepository2"]
updated_permission = art.permissions.update(permission)

Artifactory 6.6.0 or higher

from pyartifactory import Artifactory
from pyartifactory.models import PermissionV2
from pyartifactory.models.permission import PermissionEnumV2, PrincipalsPermissionV2, RepoV2, BuildV2, ReleaseBundleV2
To use PermissionV2, make sure to set api_version=2
art = Artifactory(url="ARTIFACTORYURL", auth=('USERNAME','PASSWORDORAPIKEY'), api_version=2)
Create a permission
permission = PermissionV2(
    name="test_permission",
    repo=RepoV2(
        repositories=["test_repository"],
        actions=PrincipalsPermissionV2(
            users={
                "test_user": [
                    PermissionEnumV2.read,
                    PermissionEnumV2.annotate,
                    PermissionEnumV2.write,
                    PermissionEnumV2.delete,
                ]
            },
            groups={
                "developers": [
                    PermissionEnumV2.read,
                    PermissionEnumV2.annotate,
                    PermissionEnumV2.write,
                    PermissionEnumV2.delete,
                ],
            },
        ),
        includePatterns=["**"],
        excludePatterns=[],
    ),
    build=BuildV2(
          actions=PrincipalsPermissionV2(
              users={
                  "test_user": [
                      PermissionEnumV2.read,
                      PermissionEnumV2.write,
                  ]
              },
              groups={
                  "developers": [
                      PermissionEnumV2.read,
                      PermissionEnumV2.write,
                  ],
              },
          ),
          includePatterns=[""],
          excludePatterns=[""],
      ),
    releaseBundle=ReleaseBundleV2(
          repositories=["release-bundles"],
          actions=PrincipalsPermissionV2(
              users={
                  "test_user": [
                      PermissionEnumV2.read,
                  ]
              },
              groups={
                  "developers": [
                      PermissionEnumV2.read,
                  ],
              },
          ),
          includePatterns=[""],
          excludePatterns=[""],
      )
  # You don't have to set all the objects repo, build and releaseBundle
  # If you only need repo for example, you can set only the repo object
)
perm = art.permissions.create(permission)
Update permission
permission.repo.repositories = ["testrepository2"]
updated_permission = art.permissions.update(permission)

Delete a permission:

art.permissions.delete("test_permission")

Artifacts

Get the information about a file or folder

artifactinfo = art.artifacts.info("<ARTIFACTPATHINARTIFACTORY>")
file_info = art.artifacts.info("my-repository/my/artifact/directory/file.txt")
folder_info = art.artifacts.info("my-repository/my/artifact/directory")

Deploy an artifact

artifact = art.artifacts.deploy("<LOCALFILELOCATION>", "<ARTIFACTPATHIN_ARTIFACTORY>")
artifact = art.artifacts.deploy("Desktop/myNewFile.txt", "my-repository/my/new/artifact/directory/file.txt")

Deploy an artifact with properties

artifact = art.artifacts.deploy("<LOCALFILELOCATION>", "<ARTIFACTPATHIN_ARTIFACTORY>", "<PROPERTIES>")
artifact = art.artifacts.deploy("Desktop/myNewFile.txt", "my-repository/my/new/artifact/directory/file.txt", {"retention": ["30"]})

Deploy an artifact by checksums

artifact = art.artifacts.deploy("<LOCALFILELOCATION>", "<ARTIFACTPATHINARTIFACTORY>", checksumenabled=True)
artifact = art.artifacts.deploy("Desktop/myNewFile.txt", "my-repository/my/new/artifact/directory/file.txt", checksums=True)

Deploy an artifact to the specified destination by checking if the artifact content already exists in Artifactory.

If Artifactory already contains a user-readable artifact with the same checksum the artifact content is copied over to the new location and returns a response without requiring content transfer.

Otherwise, a 404 error is returned to indicate that content upload is expected in order to deploy the artifact.

Note: The performance might suffer when deploying artifacts with checksums enabled.

Download an artifact

artifact = art.artifacts.download("<ARTIFACTPATHINARTIFACTORY>", "<LOCALDIRECTORY_PATH>")
artifact = art.artifacts.download("my-artifactory-repository/my/new/artifact/file.txt", "Desktop/my/local/directory")
The artifact location is returned by the download method
If you have not set a <LOCALDIRECTORYPATH>, the artifact will be downloaded in the current directory

Retrieve artifact list

artifacts = art.artifacts.list("<ARTIFACTPATHIN_ARTIFACTORY>")
filesonly = art.artifacts.list("<ARTIFACTPATHINARTIFACTORY>", list_folders=False)
nonrecursive = art.artifacts.list("<ARTIFACTPATHINARTIFACTORY>", recursive=False)
maxdepth = art.artifacts.list("<ARTIFACTPATHINARTIFACTORY>", depth=3)

Retrieve artifact properties

artifactproperties = art.artifacts.properties("<ARTIFACTPATHINARTIFACTORY>")  # returns all properties
artifact_properties = art.artifacts.properties("my-repository/my/new/artifact/directory/file.txt")
artifactproperties = art.artifacts.properties("<ARTIFACTPATHINARTIFACTORY>", ["prop1", "prop2"])  # returns specific properties
artifact_properties.properties["prop1"]  # ["value1", "value1-bis"]

Set artifact properties

artifactproperties = art.artifacts.setproperties("<ARTIFACTPATHIN_ARTIFACTORY>", {"prop1": ["value"], "prop2": ["value1", "value2", "etc"})  # recursive mode is enabled by default
artifactproperties = art.artifacts.setproperties("<ARTIFACTPATHIN_ARTIFACTORY>", {"prop1": ["value"], "prop2": ["value1", "value2", "etc"]}, False) # disable recursive mode

Update artifact properties

artifactproperties = art.artifacts.updateproperties("<ARTIFACTPATHIN_ARTIFACTORY>", {"prop1": ["value"], "prop2": ["value1", "value2", "etc"})  # recursive mode is enabled by default
artifactproperties = art.artifacts.updateproperties("<ARTIFACTPATHIN_ARTIFACTORY>", {"prop1": ["value"], "prop2": ["value1", "value2", "etc"}, False) # disable recursive mode

Retrieve artifact stats

artifactstats = art.artifacts.stats("<ARTIFACTPATHINARTIFACTORY>")
artifact_stats = art.artifacts.stats("my-repository/my/new/artifact/directory/file.txt")

Copy artifact to a new location

artifact = art.artifacts.copy("<CURRENTARTIFACTPATHINARTIFACTORY>","<NEWARTIFACTPATHINARTIFACTORY>")
If you want to run a dryRun test, you can do the following:
artifact = art.artifacts.copy("my-repository/current/artifact/path/file.txt","my-repository/new/artifact/path/file.txt", dryrun=True)
It will return properties of the newly copied artifact

Move artifact to a new location

artifact = art.artifacts.move("<CURRENTARTIFACTPATHINARTIFACTORY>","<NEWARTIFACTPATHINARTIFACTORY>")
You can also run a dryRun test with the move operation
It will return properties of the newly moved artifact

Delete an artifact

art.artifacts.delete("<ARTIFACTPATHIN_ARTIFACTORY>")

Builds

Get a list of all builds

build_list: BuildListResponse = art.builds.list()

Get a list of build runs

buildruns: BuildRuns = art.builds.getbuildruns("<buildname>")

Get the information about a build

buildinfo: BuildInfo = art.builds.getbuildinfo("<buildname>", "<build_number>")

Note: optional BuildProperties can be used to query the correct build info of interest.

buildproperties = BuildProperties(diff="<olderbuild>")
buildinfo: BuildInfo = art.builds.getbuildinfo("<buildname>", "<buildnumber>", properties=buildproperties)
buildinfo contains diff between <buildnumber> and <older_build>

# started is the earliest build time to return
build_properties = BuildProperties(started="<yyyy-MM-dd'T'HH:mm:ss.SSSZ>")
buildinfo: BuildInfo = art.builds.getbuildinfo("<buildname>", "<buildnumber>", properties=buildproperties)

Create build

buildcreaterequest = BuildCreateRequest(name="<buildname>", number="<buildnumber>", started="<Build start time in the format of yyyy-MM-dd'T'HH:mm:ss.SSSZ>")
createbuild = art.builds.createbuild(buildcreaterequest)

Promote a build

buildpromoterequest = BuildPromotionRequest(sourceRepo="<source-jfrog-repo>", targetRepo="<target-jfrog-repo>")
promotebuild: BuildPromotionResult = art.builds.promotebuild("<buildname>", "<buildnumber>", buildpromoterequest)

Delete one or more builds

builddeleterequest = BuildDeleteRequest(buildName="<buildname>", buildNumbers=["<buildnumber>", "<anotherbuildnumber>", ...])
art.builds.delete(builddeleterequest)

Delete all build numbers of a build

builddeleterequest = BuildDeleteRequest(buildName="<build_name>", deleteAll=True)
art.builds.delete(builddeleterequest)

Rename a build

art.builds.buildrename("<buildname>", "<newbuildname>")

Get differences between two builds

builddiffs: BuildDiffResponse = art.builds.builddiff("<buildname>", "<buildnumber>", "<olderbuildnumber>")

Contributing

Please read the Development - Contributing guidelines.

🔗 More in this category