API description¶

Core¶

Main API access¶

class osctiny.osc.Osc(url: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None, verify: Optional[str] = None, ssh_key_file: Union[pathlib.Path, str, None] = None)[source]¶

Build service API client

An instance of Osc provides all the extensions and access to the API as attributes, e.g. to get a list of groups use:

instance = Osc(*args, **kwargs)
instance.groups.get_list()

Extensions¶
Extension	Accessible through attribute
`osctiny.extensions.packages.Package`	`packages`
`osctiny.extensions.projects.Project`	`projects`
`osctiny.extensions.bs_requests.Request`	`requests`
`osctiny.extensions.search.Search`	`search`
`osctiny.extensions.users.Group`	`groups`
`osctiny.extensions.users.Person`	`users`
`osctiny.extensions.build.Build`	`build`
`osctiny.extensions.comments.Comment`	`comments`
`osctiny.extensions.distributions.Distribution`	`distributions`
`osctiny.extensions.origin.Origin`	`origins`

Parameters:	url – API URL of a BuildService instance username – Username password – Password; this is either the user password (`ssh_key_file` is `None`) or the SSH passphrase, if `ssh_key_file` is defined verify – See SSL Cert Verification for more details ssh_key_file – Path to SSH private key file
Raises:	osctiny.errors.OscError – if no credentials are provided

New in version 0.1.1: The cache parameter and the build extension

New in version 0.1.8: The comments extension

New in version 0.2.2: The issues extension

New in version 0.2.3: The distributions extension

New in version 0.3.0: The origins extension

Changed in version 0.4.0: Raises an exception when no credentials are provided

Changed in version 0.6.0: Support for 2FA authentication (i.e. added the ssh_key_file parameter and changed the meaning of the password parameter

Changed in version 0.8.0: Removed the cache parameter

cookies¶: Access session cookies

download(url, destdir, destfile=None, overwrite=False, **params)[source]¶

Shortcut for a streaming GET request

Parameters:	url (str) – Download URL destdir (pathlib.Path) – Destination directory destfile (str) – Target file name. If not specified, it will be taken from the URL overwrite (bool) – switch to overwrite existing downloaded file params – Additional query params
Returns:	absolute path to file or `None`

New in version 0.7.0.

get_boolean_params(url: str, method: str) → Tuple[str][source]¶: Get the actual boolean parameter for url and method

New in version 0.7.3.

get_objectified_xml(response)[source]¶

Return API response as an XML object

Changed in version 0.1.6: Allow parsing of “huge” XML inputs

Changed in version 0.2.4: Allow response to be a string

Parameters:	response – An API response or XML string
Rtype response:	`requests.Response`
Returns:	`lxml.objectify.ObjectifiedElement`

handle_params(url: str, method: str, params: Union[bytes, str, _io.StringIO, _io.BytesIO, _io.BufferedReader, dict]) → bytes[source]¶

Translate request parameters to API conform format

Note

The build service does not handle URL-encoded Unicode well. Therefore, parameters are encoded as bytes.

Warning

The build service does not declare its parameters properly and developers do not intend to fix this server-side. If you want to use _boolean_ parameters, make sure to use True and False. If you use 0 or 1 instead, you might receive unexpected results.

Parameters:	params (dict or str or io.BufferedReader) – Request parameter url (str) – URL to which the parameters will be sent method (str) – HTTP method to send request
Returns:	converted data ready to be used in HTTP request
Return type:	dict or bytes

Changed in version 0.7.3: Added the url and method parameters

parser¶: Explicit parser instance

request(url, method='GET', stream=False, data=None, params=None, raise_for_status=True, timeout=None)[source]¶

Perform HTTP(S) request

data is URL-encoded and passed on as GET parameters. If data is a dictionary and contains a key comment, this value is passed on as a POST parameter.

if raise_for_status is True, the used requests framework will raise an exception for occured errors.

Changed in version 0.1.2: Added parameters raise_for_status

Changed in version 0.1.3:

Added parameter timeout
Transfer data as GET parameters (except for comments and texts)

Changed in version 0.1.5: Retry sending the request, if the remote host disconnects

New in version 0.1.7: Added parameter params

Changed in version 0.5.0: Added logging of request/response

Parameters:	url – Full URL method – HTTP method stream – Delayed access, see Body Content Workflow data – Data to be included as POST parameters in request params – Additional GET parameters to be included in request raise_for_status – See requests.Response.raise_for_status timeout – Request timeout. See Timeouts
Returns:	`requests.Response`

session¶: Session object

Extensions¶

Build result extension¶

class osctiny.extensions.buildresults.Build(osc_obj)[source]¶

Osc extension for retrieving build results

cmd(project, cmd, **params)[source]¶

Execute cmd for project and get response

New in version 0.6.2.

Parameters:	project (str) – Project name cmd (str) – Command to execute params – Additional parameters

download_binary(project, repo, arch, package, filename, destdir, destfile=None, overwrite=False)[source]¶

Download binary file to disk

Parameters:	project – Project name repo – Repository name arch – Architecture name package – Package name filename – File name destdir (pathlib.Path) – Destination directory destfile (str) – Target file name. If not specified, it will be taken from the URL overwrite (bool) – switch to overwrite existing downloaded file
Returns:	Path of downloaded file
Return type:	pathlib.Path

New in version 0.7.0.

get(project, package=None, repo=None, **params)[source]¶

Get build infos

If no parameters are supplied, a compact list of build states for all packages in the project are returned.

If a package and/or repo are supplied, an extended list of build results for these particular values is returned.

Parameters:	project – Project name package – Package name repo – Repository name params – Additional parameters
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

New in version 0.1.1.

get_binary(project, repo, arch, package, filename, raw=False)[source]¶

Get the content of file

Note

This method decodes the content of the file and returns a Python string by default.

Parameters:	project – Project name repo – Repository name arch – Architecture name package – Package name filename – File name raw – If `True`, return a byte string. Otherwise, a string is returned
Returns:	Content of binary file
Return type:	str or bytes

New in version 0.2.4.

Changed in version 0.7.0: Added the raw parameter

get_binary_list(project, repo, arch, package, **params)[source]¶

Get a list of built RPMs

Parameters:	project – Project name repo – Repository name arch – Architecture name package – Package name params – Additional parameters
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

New in version 0.1.3.

get_history(project, package, repo, arch='x86_64', **params)[source]¶

Get build history

Parameters:	project – Project name package – Package name repo – Repository name arch – Architecture name params – Additional parameters
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

New in version 0.5.0.

get_log(project, repo, arch, package)[source]¶

Get the build log of a package

Parameters:	project – Project name repo – Repository name arch – Architecture name package – Package name
Returns:	The package build log file
Return type:	str

New in version 0.8.0.

get_package_list(project, repo, arch)[source]¶

Get a list of packages for which build results exist

Parameters:	project – Project name repo – Repository name arch – Architecture name
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

New in version 0.2.4.

Comments extension¶

class osctiny.extensions.comments.Comment(osc_obj)[source]¶

The BuildService comment(s) API is accessible through this object.

add(obj_type, ids, comment, parent_id=None)[source]¶

Add a comment to object

Parameters:	obj_type (str) – Name of object type (project, package, request) ids (iterable) – IDs of object comment – Comment to be added parent_id – ID of parent comment. Default: `None`
Returns:	`True`, if successful.
Raises:	HTTPError – if comment was not saved correctly. The raised exception contains the full response object and API response.

Changed in version 0.3.0: Instead of simply returning the API response, if the comment was not added, an exception is raised.

delete(comment_id)[source]¶

Delete comment

New in version 0.1.8.

Parameters:	comment_id – ID of comment
Returns:	`True`, if successful. Otherwise API response
Return type:	bool or lxml.objectify.ObjectifiedElement

get(obj_type, ids)[source]¶

Get a list of comments for object

New in version 0.1.8.

Note

The ids argument will look like this, e.g. for a package: ('project_name', 'package_name').

Parameters:	obj_type (str) – Name of object type (project, package, request) ids (iterable) – IDs of object
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

Distributions extension¶

class osctiny.extensions.distributions.Distribution(osc_obj)[source]¶

Osc extension to interact with distributions

New in version 0.2.3.

get(distribution_id)[source]¶

Get data of one base distributions hosted on this OBS instance

Parameters:	distribution_id (int) – ID of distribution
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

get_list(include_remotes=False)[source]¶

Get list of base distributions

Parameters:	include_remotes (bool) – If `True` response will include distributions also from remote instances
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

Requests extension¶

class osctiny.extensions.bs_requests.Request(osc_obj)[source]¶

The BuildService request API is accessible through this object.

add_comment(request_id, comment, parent_id=None)[source]¶

Add a comment to a request

New in version 0.1.1.

Changed in version 0.1.8: Use internally osctiny.comments.Comment.add

Parameters:	request_id – ID of the request comment – Comment to be added parent_id – ID of parent comment. Default: `None`
Returns:	`True`, if successful. Otherwise API response
Return type:	bool or lxml.objectify.ObjectifiedElement

cmd(request_id, cmd='diff', **kwargs)[source]¶

Get the result of the specified command

Available commands:

diff: Shows the diff of all affected packages.
addreview: Assign a user or group to review
changereviewstate: Accept/Decline a review

Parameters:	request_id – ID of the request cmd – Name of the command view – One of: `xml` or nothing unified – ??? missingok – ??? filelimit – ??? expand – ??? withissues – ???
Returns:	plain text
Return type:	str

Changed in version 0.1.3:

Added addreview to list of allowed commands
Added validation for arguments of command changereviewstate

Deprecated since version 0.7.8:

Replaced by update()

get(request_id, withhistory=False, withfullhistory=False)[source]¶

Get one request object

Parameters:	request_id – ID of the request withhistory (bool) – includes the request history in result withfullhistory (bool) – includes the request and review history in result
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

get_comments(request_id)[source]¶

Get a list of comments for request

Changed in version 0.1.8: Use internally osctiny.comments.Comment.get

Parameters:	request_id – ID of the request
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

get_list(**params)[source]¶

Get a list or request objects

Parameters:	params – see https://build.opensuse.org/apidocs/index#73
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

update(request_id, **kwargs)[source]¶

Update request or execute command

Note

In most cases, the API returns an XML response, so this method will try to return an objectified XML element. Otherwise, if parsing fails due to a syntax error, the response body is returned as plain text. In case of all other errors, this method lets the caller handle the exception.

Parameters:	request_id – ID of the request kwargs – See Build Service API documentation for accepted keys and values.
Returns:	Response content
Return type:	lxml.objectify.ObjectifiedElement or plain text

New in version 0.7.8.

Issues extension¶

class osctiny.extensions.issues.Issue(osc_obj)[source]¶

The BuildService issue(-tracker) API is accessible through this object.

New in version 0.2.2.

get(tracker, name, force_update=False)[source]¶

Get details for an issue

Parameters:	tracker (str) – issue tracker name name (str) – issue name force_update (bool) – If `True`, BuildService will update the issue details internally prior to returning the response
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

get_tracker(name)[source]¶

Get information on one issue tracker

Parameters:	name (str) – issue tracker name
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

get_trackers[source]¶: Get all issue trackers with data

Origin extension¶

This is a runtime optimized implementation of the Origin Manager.

The intention of this implementation is to quickly yield batch results. In doing so a different logic than in the original OSC plugin is used:

If a project inherits a package from another project, the origin is checked for the package in the original project.
If the package has received submissions from potential origin projects, only those projects are considered.
The first project from the origin configuration (including above limitations) containing the package is considered as origin project.
If a project was found and if that project inherits the package, the original project is returned.

New in version 0.3.0.

class osctiny.extensions.origin.DevelProjects(osc_obj, **kwargs)[source]¶

Lazy lookup table for package specific development projects

get_devel_projects(*projects)[source]¶

Find package specific development projects for (maintained) projects

Parameters:	projects (str) – One or more project names
Returns:	Dictionary with development projects per package
Return type:	dict

class osctiny.extensions.origin.Origin(osc_obj)[source]¶

Query tool to find the origin of packages in maintained projects

New in version 0.3.0.

devel_projects¶

Delayed initialization of the package specific development project dictionary

This dictionary is populated in a lazy/JIT fashion.

Returns:	`DevelProjects`

expanded_origins¶

Expand the projects from the Origin Configuration

This property returns all the expanded origin projects for all projects that have the OSRT:OriginConfig attribute set in build service.

Note

Even if OSRT:OriginConfig explicitly defines a bogus order of projects, e.g.

SUSE:SLE-15:Update
SUSE:SLE-15-SP1:Update
SUSE:SLE-15-SP2:Update

this method will rearrange the projects in a meaningful way, e.g. into:

SUSE:SLE-15-SP2:Update
SUSE:SLE-15-SP1:Update
SUSE:SLE-15:Update

Consider this a workaround for this issue.

Returns:	Dictionary with lists of origin project names for all projects
Return type:	dict

family_sort_key(key)[source]¶

Provides a numeric key for sorting projects of the same family

Parameters:	key (str) – Project name
Returns:	Numeric value representing the version and priority of projects
Return type:	float

family_sorter(unsorted_list)[source]¶

Sort consecutive projects of the same family

In case the configuration does not list the projects in a meaningful way, they are sorted now to avoid the need to check the package histories for every package.

Note

This sorter is only allowed to change the order of consecutive projects belonging to the same family.

Consider this a workaround for this issue.

Parameters:	unsorted_list (list of str) – List with project names
Returns:	Generator with sorted list items
Return type:	generator

find_package_origin(package, project, resolve_inheritance=True)[source]¶

Find the origin project for package in project

This method will return simply None for patchinfo packages and packages with an incident ID as suffix.

Important

When you want to check multiple packages by multiple calls to this method, you should resolve from where project inherits the package for all your (package, project) pairs in advance and set resolve_inheritance to False to speed up the response time.

Parameters:	package (str) – Package name project (str) – Project name resolve_inheritance (bool) – Trigger to cause this method to replace `project` with the project from which `package` is inherited from
Returns:	Origin project name or `None`
Return type:	str

get_origin_from_submissions(package, project)[source]¶

Get potential origin projects from accepted submissions (aka. requests)

This method returns the source project names from accepted requests.

Parameters:	package (str) – Target package name project (str) – Target project name
Returns:	Set of source project names
Return type:	set or str

get_project_origin_config[source]¶

Get the Origin configuration for project

This method returns the decoded YAML data, e.g. for “openSUSE:Leap:15.2:Update”:

{
  "origins": [
    {
      "<devel>": {}
    },
    {
      "SUSE:SLE-15:Update": {
        "maintainer_review_initial": false
      }
    },
    {
      "SUSE:SLE-15-SP1:Update": {
        "maintainer_review_initial": false
      }
    },
    {
      "SUSE:SLE-15-SP2:Update": {
        "maintainer_review_initial": false
      }
    },
    {
      "openSUSE:Leap:15.1:Update": {
        "pending_submission_allow": true
      }
    },
    {
      "openSUSE:Factory": {
        "pending_submission_allow": true
      }
    },
    {
      "*~": {}
    }
  ],
  "fallback-group": "origin-reviewers-maintenance"
}

Parameters:	project (name) – The project name
Returns:	Configuration content
Return type:	dict

is_linked[source]¶

Guess whether a package is a link source (with incident number as suffix).

Parameters:	package – Package name to check project – Project name containing the package
Returns:	`True`, if package name seems to have an incident ID as suffix

list(project)[source]¶

List all packages in a maintained project and their origin projects

Parameters:	project (str) – Project name
Returns:	Generator of pairs: (‘pkg’, ‘origin’)
Return type:	generator

maintained_projects¶

Get the list of maintained projects

Maintained projects are identified by the presence of the OBS:Maintained attribute.

Returns:	Project names
Return type:	List of str

Changed in version 0.4.0: Search maintained projects via the OBS:Maintained attribute and not via the maintenance project.

maintenance_project¶

Get the maintenance project

This project is important, because it’s meta can provide the list of maintained projects.

Returns:	Project name or `None`
Return type:	str or None

Changed in version 0.4.0: Return string instead of XML object

package_matrix¶

Delayed initialization of the lookup package matrix.

The matrix is populated in a lazy/JIT fashion.

Returns:	`PackageMatrix`

class osctiny.extensions.origin.PackageMatrix(osc_obj, expanded_origins, **kwargs)[source]¶

Lazy lookup matrix for package origins

This matrix collects for every project (provided as key) a dictionary with all allowed origin projects and packages therein. If the origin project inherits the package from another project, this information is available, too.

The matrix is not populated at initialization time. When the matrix for a project is requested for the first, only the corresponding items are populated. Subsequent access to the same project does not trigger new population. Hence “lazy”.

Example:

{
    'openSUSE:Leap:15.2:Update': {
        'SUSE:SLE-15-SP2:Update': {
            # ...
            'zeromq': ['SUSE:SLE-15:Update'],
            'zypper': ['SUSE:SLE-15-SP2:Update', 'SUSE:SLE-15-SP2:GA']
        },
        'SUSE:SLE-15-SP1:Update': {
            'zinnia-tomoe': ['SUSE:SLE-15:GA']
            # ...
        },
        'openSUSE:Factory': {
            # ...
            'zziplib': ['openSUSE:Factory']
        }
    },
    'openSUSE:Leap:15.2': ...
}

Parameters:	osc_obj (`osctiny.osc.Osc`) – An Osc instance to run queries expanded_origins (`Origin.expanded_origins()`) – Lookup dictionary with all possible origin projects

Packages extension¶

class osctiny.extensions.packages.Package(osc_obj)[source]¶

Osc extension to interact with packages

add_comment(project, package, comment, parent_id=None)[source]¶

Add a comment to a package

Changed in version 0.1.8: Use internally osctiny.comments.Comment.add

Parameters:	project – name of project package – name of package comment – Comment to be added parent_id – ID of parent comment. Default: `None`
Returns:	`True`, if successful. Otherwise API response
Return type:	bool or lxml.objectify.ObjectifiedElement

aggregate(src_project, src_package, tgt_project, tgt_package, publish=True, repo_map=None, no_sources=False)[source]¶

Aggregate a package to another package

New in version 0.1.2.

Changed in version 0.2.5: When creating a new aggregate package, the build flag is always enabled.

Parameters:

src_project – Name of source project
src_package – Name of source package
tgt_project – Name of target project
tgt_package – Name of target package
publish – En-/Disable publishing of aggregated package
repo_map (None or dict) – Optional repository mapping
no_sources – If True, ignore source packages when copying build results to destination project

Returns:

checkout(project, package, destdir, rev=None, meta=False, expand=False)[source]¶

Checkout all files and directories of package

Note

Only by using checkout() the directory structure is compatible with the osc command line tool!

Parameters:	project – name of project package – name of package destdir – target local directory rev – Package revision to check out meta – Checkout meta files instead expand – If `True` and the package is a link, download the file from the linked package
Returns:	nothing

New in version 0.1.1.

Changed in version 0.3.3: Added the parameter expand

static cleanup_params(**params) → Union[dict, str][source]¶

Prepare query parameters

The build service is inconsistent in its validation of parameters. In most cases it does not complain about excess parameters, in some it complains about unexpected ones.

Parameters:	params – Query parameters
Returns:	The original dictionary of query parameters or a subset of it

New in version 0.7.4.

Changed in version 0.7.7: Handle more inconsistencies in the API endpoints

cmd(project, package, cmd, **params)[source]¶

Get the result of the specified command

Available commands:

diff: Shows the diff of all affected packages.
showlinked: List all package instances linking to this one.
instantiate: Instantiate a package container, which is available via project links only so far.
release: Releases sources and binaries of that package.
unlock: Unlocks a locked package.
branch: Create a source link from a package of an existing project.
set_flag: Modify or set a defined flag for package
createSpecFileTemplate: Create template for RPM SPEC file.
commit: Commits package changes to buildservice.
collectbuildenv: Creates _buildenv files based on origin package builds.
importchannel: Import a kiwi channel file for OBS.

Note

Command diff

The diff command returns plain text, instead of XML, by default! To get XML, pass the view='xml' param.

Parameters:	project – name of project package – name of package cmd – name of command params – More command specific parameters. See https://build.opensuse.org/apidocs/index
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement or str

delete(project, package, force=False, comment=None)[source]¶

Delete package

New in version 0.1.2.

Parameters:	project – Project name package – Package name force – Delete package even if pending requests exist comment – Optional comment
Returns:	`True`, if successful. Otherwise API response
Return type:	bool or lxml.objectify.ObjectifiedElement

download_file(project, package, filename, destdir, meta=False, overwrite=False, rev=None, expand=False)[source]¶

Download a file to directory

Parameters:	project – name of project package – name of package filename – name of file destdir – path of directory meta – switch to meta files overwrite – switch to overwrite existing downloaded file rev – Download file from this specific package revision expand – If `True` and the package is a link, download the file from the linked package
Returns:	absolute path to file or `None`
Raises:	OSError – if something goes wrong

New in version 0.1.1: Parameter rev

Changed in version 0.3.3: Added the parameter expand

Changed in version 0.7.0: Moved some logic to osctiny.osc.Osc.download()

exists(project, package, filename=None) → bool[source]¶

Check whether package or file in package exists

New in version 0.1.2.

Parameters:	project – Project name package – Package name filename – Name of file
Returns:	`True`, if package exists, otherwise `False`

get_attribute(project, package, attribute=None)[source]¶

Get one attribute of a package

Parameters:	project – name of project package – name of package attribute – name of attribute
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

get_comments(project, package)[source]¶

Get a list of comments for package

New in version 0.1.8: Use internally osctiny.comments.Comment.get

Parameters:	project – name of project package – name of package
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

get_file(project, package, filename, meta=False, rev=None, expand=False)[source]¶

Get a source file

Downloads a specific file from a package and returns a response object from which the file contents can be read.

Parameters:	project – name of project package – name of package filename – name of file meta – switch to meta files rev – Get file from this specific package revision expand – If the package is linked, it typically only contains a `_link` file. In order to allow retrieval of the linked package instead of a 404 error, set this parameter to ‘1’
Returns:	response
Return type:	requests.Response

New in version 0.1.1: Parameter rev

New in version 0.1.11: Parameter expand

get_files(project, package, **params)[source]¶

List package files

Parameters:	project – name of project package – name of package params – more optional parameters. See: https://build.opensuse.org/apidocs/index#45
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

get_history(project, package)[source]¶

Get history of package

Parameters:	project – name of project package – name of package
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

get_list(project: str, deleted: bool = False, expand: bool = False, **params)[source]¶

Get packages from project

New in version 0.1.7: Parameter deleted

New in version 0.7.0: Parameter expand

New in version 0.7.4: Parameter params

Changed in version 0.7.6: Changed default value of expand to False

Parameters:	project – name of project deleted – Show deleted packages instead expand – Include inherited packages and their project of origin
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

get_meta(project, package, blame=False)[source]¶

Get package metadata

Note

When blame annotations are requested no XML object can be returned!

Changed in version 0.1.2: Added parameter blame

Parameters:	project – name of project package – name of package blame – Show metadata with change annotations
Returns:	Objectified XML element or str
Return type:	lxml.objectify.ObjectifiedElement or str

push_file(project, package, filename, data, comment=None)[source]¶

Upload a file to package

Parameters:	project – Name of project package – Name of package filename – Name of file data (str or open file handle) – content of file comment – Optional comment to use as commit message

Changed in version 0.5.0: Added an optional comment argument to be used as the commit message when writing the file.

set_meta(project, package, title=None, description=None, meta=None, comment=None)[source]¶

Set package metadata

Note

By setting the meta data package is created, if it does not exist.

Specify title and description to create an XML file with minimum content or provide a complete XML string via meta.

Note

If title or description is given in combination with meta, the existing values in meta will be overwritten.

New in version 0.1.2.

Changed in version 0.7.8: Added an optional comment argument to be used as commit message

Parameters:	project – Project name package – New package name title – Title for meta description – Description for meta meta (str or lxml.objectify.ObjectifiedElement) – New content for meta comment – Optional comment to use as commit message
Returns:

Projects extension¶

class osctiny.extensions.projects.Project(osc_obj)[source]¶

Osc extension to interact with projects

add_comment(project, comment, parent_id=None)[source]¶

Add a comment to a project

Changed in version 0.1.8: Use internally osctiny.comments.Comment.add

Parameters:	project – name of project comment – Comment to be added parent_id – ID of parent comment. Default: `None`
Returns:	`True`, if successful. Otherwise API response
Return type:	bool or lxml.objectify.ObjectifiedElement

create(project, metafile=None, title=None, description=None, bugowner=None, maintainer=None, comment=None, force=False)¶

Edit project meta data or create a new project

If no metafile is provided, a default template is used.

New in version 0.7.2.

Changed in version 0.7.8: Added an optional comment argument to be used as commit message

Changed in version 0.7.11: Added an optional force argument to allow changing the meta even when IBS reports repository dependency problems

Parameters:	project – name of project metafile (str or ElementTree) – Complete metafile title – Title for meta file description – Description for meta file bugowner – Bugowner for meta file maintainer – Maintainer for meta file comment – Optional comment to use as commit message force – Whether to force a meta change, even if there are repo dependency errors
Returns:	`True`, if successful. Otherwise API response
Return type:	bool or lxml.objectify.ObjectifiedElement

delete(project, force=False, comment=None)[source]¶

Delete project

New in version 0.1.2.

Parameters:	project – Project name force – Delete project even if subprojects, packages or pending requests for those packages exist comment – Optional comment
Returns:	`True`, if successful. Otherwise API response
Return type:	bool or lxml.objectify.ObjectifiedElement

delete_attribute(project, attribute)[source]¶

Delete an attribute of a project

Parameters:	project – name of project attribute – name of attribute
Returns:	`True`, if successful. Otherwise API response
Return type:	bool or lxml.objectify.ObjectifiedElement

exists(project)[source]¶

Check whether project exists

New in version 0.1.2.

Parameters:	project – Project name
Returns:	`True`, if project exists, otherwise `False`

get_attribute(project, attribute=None)[source]¶

Get one attribute of a project

Note

Be aware of namespace prefixes.

When specifying the attribute argument make sure to include the namespace prefix and separate both by a colon, e.g. OBS:IncidentPriority.

Parameters:	project – name of project attribute – name of attribute
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

get_comments(project)[source]¶

Get a list of comments for project

Changed in version 0.1.8: Use internally osctiny.comments.Comment.get

Parameters:	project – name of project
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

get_config(project, revision=None)[source]¶

Get project configuration

New in version 0.7.10.

Parameters:	project – name of project revision – optional revision of the config to get
Returns:	The project configuration as string
Return type:	str

get_files(project, directory='', meta=False, rev=None, **kwargs)[source]¶

List project files

Parameters:	project – name of project directory – directory in project meta (bool) – switch for _meta files rev (int) – revision kwargs – More keyword arguments for API call
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

Deprecated since version 0.7.4: Use osctiny.extensions.packages.Package.get_files() or osctiny.extensions.packages.Package.get_list() instead.

The API URL used by this method is (depending on the value of directory) identical to the one used by the above two methods.

get_history(project, meta=True, rev=None, **kwargs)[source]¶

Get history of project

To get just a particular revision, use the rev argument.

Parameters:	project – name of project meta (bool) – Switch between meta and non-meta (normally empty) revision history rev – History revision ID
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

get_list(deleted=False)[source]¶

Get list of projects

Parameters:	deleted (bool) – show deleted projects instead of existing
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

get_meta(project)[source]¶

Get project metadata

Parameters:	project – name of project
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

put_meta(project, metafile=None, title=None, description=None, bugowner=None, maintainer=None)[source]¶

Edit project meta data or create a new project

If no metafile is provided, a default template is used.

New in version 0.1.5.

Deprecated since version 0.7.2: Use set_meta() instead

Parameters:	project – name of project metafile (str or ElementTree) – Complete metafile title – Title for meta file description – Description for meta file bugowner – Bugowner for meta file maintainer – Maintainer for meta file
Returns:	`True`, if successful. Otherwise API response
Return type:	bool or lxml.objectify.ObjectifiedElement

set_attribute(project, attribute, value)[source]¶

Set or update an attribute of a project

Parameters:	project – project name attribute – attribute name (can include prefix separated by colon) value – attribute value or list of values
Returns:	`True`, if successful. Otherwise API response
Return type:	bool or lxml.objectify.ObjectifiedElement

Changed in version 0.7.0: Support attributes with multiple values

set_config(project, config=None, comment=None)[source]¶

Set project config data

New in version 0.7.10.

Parameters:	project – name of project config (str) – Complete configuration to set comment – Optional comment to use as commit message
Returns:	`True`, if successful. Otherwise, API response
Return type:	bool or lxml.objectify.ObjectifiedElement

set_meta(project, metafile=None, title=None, description=None, bugowner=None, maintainer=None, comment=None, force=False)[source]¶

Edit project meta data or create a new project

If no metafile is provided, a default template is used.

New in version 0.7.2.

Changed in version 0.7.8: Added an optional comment argument to be used as commit message

Changed in version 0.7.11: Added an optional force argument to allow changing the meta even when IBS reports repository dependency problems

Parameters:	project – name of project metafile (str or ElementTree) – Complete metafile title – Title for meta file description – Description for meta file bugowner – Bugowner for meta file maintainer – Maintainer for meta file comment – Optional comment to use as commit message force – Whether to force a meta change, even if there are repo dependency errors
Returns:	`True`, if successful. Otherwise API response
Return type:	bool or lxml.objectify.ObjectifiedElement

Persons and groups extension¶

class osctiny.extensions.users.Group(osc_obj)[source]¶

The BuildService group API is accessible through this object.

get(title)[source]¶

Get details for group title

Parameters:	title – Title/name of the group
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

get_list(login=None)[source]¶

Get all groups or all groups containing user login

Parameters:	login – Username to filter for
Return type:	lxml.objectify.ObjectifiedElement

class osctiny.extensions.users.Person(osc_obj)[source]¶

The BuildService person API is accessible through this object.

get(userid)[source]¶

Get details for user userid

Parameters:	userid – Username
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

Search extension¶

class osctiny.extensions.search.Search(osc_obj)[source]¶

Osc extension providing methods for searching

search(path, xpath, **kwargs)[source]¶

Search for objects in buildservice

Note

Shortcuts

There are shortcut method for the object types project, package and request. These only expect the xpath argument, e.g.:

Osc.search.project("starts-with(@name,'SUSE:Maintenance')")

Note

Pagination

Search results can be paginated using limit and offset, e.g.

Osc.search.project("starts-with(@name,'SUSE:Maintenance')",
                   limit=10, offset=30)

Parameters:	path – object type / relative URL xpath – XPath expression to filter results kwargs – Additional parameters to be passed to the underlying API
Returns:	Objectified XML element
Return type:	lxml.objectify.ObjectifiedElement

Utilities¶

Authentication handlers for 2FA¶

New in version 0.6.0.

class osctiny.utils.auth.HttpSignatureAuth(username: str, password: Optional[str], ssh_key_file: pathlib.Path)[source]¶

Implementation of the “Signature authentication scheme”

Note

This seems to be a variation of the HTTP Message Signatures specification.

See also the blog post describing the implementation and the reference implementation for osc.

Note

It is recommended to use SSH keys with a passphrase.
If ssh-agent is running, the passphrase is not required at initialization of this class.
If you use an SSH key without passphrase, you don’t need to specify it.

Parameters:	username – The username password – Passphrase for SSH key ssh_key_file – Path of SSH key

build_digest_header(method: str, url: str) → str[source]¶: Generate Authentication header

get_auth_header(r: requests.models.Response) → str[source]¶

Extract the relevant header for Signature authentication

Parameters:	r – Response
Returns:	Header text

handle_401(r: requests.models.Response, **kwargs) → requests.models.Response[source]¶

Handle authentication in case of 401

Contents of method copied from requests.auth.HTTPDigestAuth.handle_401() and edited

split_headers(headers: str) → List[str][source]¶

Split headers parameter from WWW-Authenticate Signature header

Parameters:	headers – Value of the `headers` parameter

ssh_sign() → str[source]¶: Solve the challenge via SSH signing

osctiny.utils.auth.get_auth_header_from_orignal_response(r: requests.models.Response) → Optional[str][source]¶: Extract the “www-authenticate” header from the private original response attribute of a response

New in version 0.7.6.

osctiny.utils.auth.get_auth_header_from_response(r: requests.models.Response) → Optional[str][source]¶: Extract the “www-authenticate” header from the response

New in version 0.7.6.

osctiny.utils.auth.is_ssh_key_readable(ssh_key_file: pathlib.Path, password: Optional[str]) → Tuple[bool, Optional[str]][source]¶

Check whether SSH signing is viable

Parameters:	ssh_key_file – Path to SSH key password – Passphrase
Returns:	`True`, if SSH key is accessible

New in version 0.6.3.

Changed in version 0.7.8:

Moved from HttpSignatureAuth.is_ssh_agent_available

Changed in version 0.7.10:

Return the error message, if key cannot be unlocked

Changed in version 0.7.12:

Instead of checking whether the key is readable, this function checks whether it can actually be used for signing

osctiny.utils.auth.ssh_sign(message: str, namespace: str, ssh_key_file: pathlib.Path, password: Optional[str] = None) → str[source]¶

Create an SSH signature for message

Parameters:	message – The message/data to sign namespace – The purpose of the signature (see SSH docs for details) ssh_key_file – Path to SSH key password – Passphrase
Returns:	Signature

New in version 0.7.12.

Base classes for osc-tiny specific exceptions¶

exception osctiny.utils.errors.OscError[source]¶: Base class for expcetions to be raised by osctiny

Common base classes¶

class osctiny.utils.base.DataDir(osc, path, project, package=None, overwrite=False)[source]¶

Compatibility layer for the .osc data directory used by the osc CLI

write_dir_contents()[source]¶: Create files with default content in .osc sub-directory

class osctiny.utils.base.ExtensionBase(osc_obj)[source]¶: Base class for extensions of the Ocs entry point.

Changelog¶

Parser and generator for SUSE/OpenBuildService style changelog files.

This parser/generator is a reference implementation of the vc bash script from the openSUSE:Tools build package. See: https://build.opensuse.org/package/show/openSUSE:Tools/build

New in version 0.1.11.

class osctiny.utils.changelog.ChangeLog[source]¶

Provider of capabilities to parse and write a .changes file

Parsing and starting a new .changes file should be intuitive. In order to append or edit entries use this recipe:

cl = ChangeLog.parse(path="/path/to/file", generative=False)
cl.entries.append(Entry(...))
cl.write()

entry_factory

A class used to store entry data.

Example: Entry could be extended to provide a read-only property to find bug references inside the entry’s content.

entry_factory¶: alias of Entry

classmethod parse(path, generative=True)[source]¶

Parse a changes file

The changes file to parse may be specified by it’s path or as an already open file handle (aka. subclass of io.TextIOBase).

Use this method to initialize a new instance of ChangeLog like this:

cl = ChangeLog.parse(path="/path/to/file")
for entry in cl.entries:
    print(entry)

Parameters:	path (str or open file/stream handle) – If a path is supplied as a string, the file will be opened for reading. If a subclass of `io.TextIOBase` is provided, this method assumes that it is opened for reading. generative (bool) – If set to `True` (default), changelog entries are parsed on the fly using a generator. Otherwise all entries are parsed immediately and stored in an iterable.
Returns:	An instance of `ChangeLog`
Raises:	TypeError – if `path` is not a string or a subclass of `io.TextIOBase`

write(path)[source]¶

Write entries to file/stream

This method can write to files and any other stream derived from io.IOBase.

Parameters:	path (str or `io.IOBase`) – Path to file or open, writable handle

class osctiny.utils.changelog.Entry(timestamp=None, packager=None, content='')[source]¶

Representation of a complete changelog entry

timestamp¶: Timestamp of the entry as a datetime.datetime object. If no value is provided during initialization, datetime.datetime.now() is used instead.

packager¶

Email and name of the packager. Valid formats are:

email@example.com
<email@example.com>
full name <email@example.com>

content¶: All lines until the beginning of the next entry; except empty lines at the beginning and end

formatted_timestamp¶

Return properly formatted timestamp

Returns:	str

now()[source]¶

Return current UTC timestamp

Returns:	`datetime.datetime`

osctiny.utils.changelog.is_aware(timestamp)[source]¶

Check whether timestamp is timezone aware

Parameters:	timestamp – `datetime.datetime`
Returns:	`True`, if timestamp is tz-aware

Configuration utilities¶

This module provides a collection of utilities to access the configuration of osc in order to make it easier to create command line tools with OSC Tiny.

New in version 0.4.0.

osctiny.utils.conf.get_config_path() → pathlib.Path[source]¶

Return path of osc configuration file

Returns:	Path
Raises:	FileNotFoundError – if no config file found

osctiny.utils.conf.get_cookie_jar() → Optional[http.cookiejar.LWPCookieJar][source]¶: Get cookies from a persistent osc cookiejar

New in version 0.8.0.

osctiny.utils.conf.get_credentials(url: Optional[str] = None) → Tuple[str, Optional[str], Optional[pathlib.Path]][source]¶

Get credentials for Build Service instance identified by url

Important

If the osc package is not installed, this function will only try to extract the username and password from the configuration file.

Any credentials stored on a keyring will not be accessible!

Parameters:	url – URL of Build Service instance (including schema). If not specified, the value from the `apiurl` parameter in the config file will be used.
Returns:	(username, password, SSH private key path)
Raises:	ValueError – if config provides no credentials

Changed in version 0.6.3: If an SSH key is configured, this function will return None instead of a password.

Mapping types¶

This module provides a collection of mapping types with special behavior.

New in version 0.3.0.

class osctiny.utils.mapping.LazyOscMappable(osc_obj, **kwargs)[source]¶

Base class for lazy mappables

To define custom subclasses override the __missing__ method and set the missing key.

Parameters:	osc_obj (`osctiny.osc.Osc`) – An Osc instance to run queries

class osctiny.utils.mapping.Mappable(**kwargs)[source]¶

Basic implementation of a dictionary

get(k[, d]) → D[k] if k in D, else d. d defaults to None.[source]¶

keys() → a set-like object providing a view on D's keys[source]¶

values() → an object providing a view on D's values[source]¶