TravisPy¶
TravisPy is a Python API for Travis CI. It follows the official API and is implemented as similar as possible to Ruby implementation.
Experimental methods will not be supported until they become official.
For full documentation please refer to Travis CI official API documentation.
Documentation¶
Getting started¶
TravisPy works just as Travis CI: it authenticates against GitHub. So as a requirement you must have a GitHub access token with the following scopes:
- read:org
- user:email
- repo_deployment
- repo:status
- write:repo_hook
With your token in hands all is easy:
>>> from travispy import TravisPy
>>> t = TravisPy.github_auth(<your_github_token>)
>>> user = t.user()
>>> user
<travispy.entities.user.User object at 0x02C26C48>
Now you can access information related to user current logged in:
>>> user.login
'travispy'
>>> user['login']
'travispy'
To get the list of repositories that you are member of:
>>> repos = t.repos(member=user.login)
>>> len(repos) # Ordered by recent activity
5
>>> repos[0]
<travispy.entities.repo.Repo object at 0x02C26C49>
>>> repos[0].slug
'travispy/on_py34'
Or simply request for repository you want:
>>> repo = t.repo('travispy/on_py34')
<travispy.entities.repo.Repo object at 0x02C26C51>
And finally, getting build information:
>>> build = t.build(repo.last_build_id)
>>> build
<travispy.entities.build.Build object at 0x02C26C50>
>>> build.restart()
True
>>> build.cancel()
True
>>> build.cancel() # As build was already cancelled it will return False.
False
Please refer to the official API to learn more about which entities are supported. Soon a specific and detailed documentation related to this library will be available.
API¶
This document brings the public API of TravisPy.
-
travispy.travispy.
PUBLIC
= URI for Travis CI free service.¶
-
travispy.travispy.
PRIVATE
= URI for Travis CI paid service for GitHub private repositories.¶
-
travispy.travispy.
ENTERPRISE
= URI template for Travis CI service running under a personal domain. Usage will be something like ENTERPRISE % {'domain': 'http://travis.example.com'}.¶
-
class
travispy.travispy.
TravisPy
(token=None, uri='https://api.travis-ci.org')[source]¶ Instances of this class are responsible for comunicating with Travis CI, sending requests and handling responses properly. You can create as much instances as you want since each one will create a separated session.
Parameters: - token (str | None) –
Travis CI token linked to your GitHub account.
Even if you have a public repository, some information are related to your user account and not the repository itself so if token is not provided an error will be returned.
Required for private and enterprise repositories to access any information.
- uri (
PUBLIC
|PRIVATE
|ENTERPRISE
| str) – URI where Travis CI service is running.
Note
Do not confuse
token
with the one found on your profile page.-
account
(account_id)[source]¶ Parameters: account_id (int) – ID of the account to obtain information. Return type: Account
Note
This request always needs to be authenticated.
-
accounts
(all=False)[source]¶ Parameters: all (bool) – Whether or not to include accounts the user does not have admin access to. Return type: list( Account
)Returns: Information of all accounts that the user might have access.This is usually the account corresponding to the user directly and one account per GitHub organization. Note
This request always needs to be authenticated.
-
branch
(name, repo_id_or_slug, **kwargs)[source]¶ Parameters: - name (str) – Branch name that should be retrieved.
- repo_id_or_slug (int | str) – Repository where branch is located.
Return type:
-
branches
(**kwargs)[source]¶ Parameters: - repository_id (int) – Repository id the build belongs to.
- slug (str) – Repository slug the build belongs to.
Return type: list(
Branch
)Note
You have to supply either
repository_id
orslug
.
-
broadcasts
()[source]¶ Return type: list( Broadcast
)Note
This request always needs to be authenticated.
-
build
(build_id)[source]¶ Parameters: build_id (int) – ID of the build to obtain information. Return type: Build
-
builds
(**kwargs)[source]¶ Parameters: - ids (list(int)) – List of build ids to fetch.
- repository_id (int) – Repository id the build belongs to.
- slug (str) – Repository slug the build belongs to.
- number (str) – Filter by build number, requires
slug
orrepository_id
. - after_number (str) – List build after a given build number (use for pagination), requires
slug
orrepository_id
. - event_type (str) – Limit build to given event type (
push
orpull_request
).
Return type: list(
Build
)Note
You have to supply either
ids
,repository_id
orslug
.
-
classmethod
github_auth
(token, uri='https://api.travis-ci.org')[source]¶ Parameters: - token (str) – GitHub access token.
- uri – See
__init__()
Return type: Returns: A
TravisPy
instance authenticated with GitHub account.Raises: TravisError – when authentication against GitHub fails.
-
hooks
()[source]¶ Return type: list( Hook
)Returns: Returns list of existing hooks that user have access. Note
This request always needs to be authenticated.
-
jobs
(**kwargs)[source]¶ Parameters: - ids (list(int)) – List of jobs IDs.
- state (str) – Job state to filter by. Possible values are
passed
,canceled
,failed
anderrored
. - queue (str) – Job queue to filter by.
Return type: list(
Job
)Note
You need to provide exactly one of the above parameters. If you provide
state
orqueue
, a maximum of 250 jobs will be returned.
-
repo
(id_or_slug)[source]¶ Parameters: id_or_slug (int | str) – ID of slug of repository to obtain information. Return type: Repo
-
repos
(**kwargs)[source]¶ Parameters: - ids (list(int)) – List of repository ids to fetch, cannot be combined with other parameters.
- member (str) – Filter by user that has access to it (GitHub login).
- owner_name (str) – Filter by owner name (first segment of slug).
- slug (str) – Filter by slug.
- search (str) – Filter by search term.
- active (bool) – If
True
, will only return repositories that are enabled. Default isFalse
.
Return type: list(
Repo
)Note
If no parameters are given, a list of repositories with recent activity is returned.
- token (str | None) –
Entities¶
This document brings information about all entities that are used by TravisPy API.
-
class
travispy.entities._entity.
Entity
(session)[source]¶ Base class for all Travis CI entities.
Parameters: session ( Session
) – Internet session in which entity information will be requested.Variables: id (int) – The entity ID. -
classmethod
find_many
(session, **kwargs)[source]¶ Method responsible for returning as many as possible matches for current class.
Parameters: session ( Session
) – Session that must be used to search for results.Return type: list( Entity
)Raises: TravisError – when response has status code different than 200.
-
classmethod
find_one
(session, entity_id, **kwargs)[source]¶ Method responsible for returning exactly one instance of current class.
Parameters: - session (
Session
) – Session that must be used to search for result. - entity_id (int) – The ID of the entity.
Return type: Raises: TravisError – when response has status code different than 200.
- session (
-
classmethod
-
class
travispy.entities._stateful.
Stateful
(session)[source]¶ Bases:
travispy.entities._entity.Entity
Base class for stateful entities such as
Repo
,Build
andJob
.-
CANCELED
¶ Constant representing state
canceled
. Should not be changed.
-
CREATED
¶ Constant representing state
created
. Should not be changed.
-
QUEUED
¶ Constant representing state
queued
. Should not be changed.
-
STARTED
¶ Constant representing state
started
. Should not be changed.
-
PASSED
¶ Constant representing state
passed
. Should not be changed.
-
FAILED
¶ Constant representing state
failed
. Should not be changed.
-
ERRORED
¶ Constant representing state
errored
. Should not be changed.
-
READY
¶ Constant representing state
ready
. Should not be changed.
-
GREEN
¶ Constant representing state color
green
. Should not be changed.
-
YELLOW
¶ Constant representing state color
yellow
. Should not be changed.
-
RED
¶ Constant representing state color
red
. Should not be changed.
Variables: state (str) – Current state. Possible values are:
-
canceled
¶ Return type: bool Returns: True
if build process was canceled.See also
-
color
¶ Return type: bool Returns: The color related to current build state. Possible values are:
-
created
¶ Return type: bool Returns: True
if entity build process was created successfully.See also
-
errored
¶ Return type: bool Returns: True
if build process got errors.See also
-
failed
¶ Return type: bool Returns: True
if build process failed. This is usually related to failures on tests.See also
-
finished
¶ Return type: bool Returns: True
if build process is finished.
-
passed
¶ Return type: bool Returns: True
if build process was finished successfully.See also
-
pending
¶ Return type: bool Returns: True
if build was scheduled but was not finished.See also
-
queued
¶ Return type: bool Returns: True
if entity was already queued sometime in the build process.See also
-
ready
¶ Return type: bool Returns: True
if build process is ready.See also
-
running
¶ Return type: bool Returns: True
if build process is running.See also
-
started
¶ Return type: bool Returns: True
if entity was already started sometime in the build process.See also
-
unsuccessful
¶ Return type: bool Returns: True
if build process was finished unsuccessfully.
-
-
class
travispy.entities._restartable.
Restartable
(session)[source]¶ Bases:
travispy.entities._stateful.Stateful
-
class
travispy.entities.
Account
(session)[source]¶ Bases:
travispy.entities._entity.Entity
A user might have access to multiple accounts. This is usually the account corresponding to the user directly and one account per GitHub organization.
Variables: - name (str) – User or organization id.
- login (str) – Account name on GitHub.
- type (str) – Account login on GitHub.
- repos_count (int) – Number of repositories.
- subscribed (bool) – Whether or not the account has a valid subscription. Only available on Travis Pro.
- avatar_url (str) – Link to avatar.
-
class
travispy.entities.
Branch
(session)[source]¶ Bases:
travispy.entities._stateful.Stateful
Variables: - repository_id (int) – Repository ID.
- commit_id (str) – Commit ID.
- number (str) – Build number.
- config (dict) – Build config (secure values and ssh key removed). It comes from
.travis.yml
file. - started_at (str) – Time the build was started.
- finished_at (str) – Time the build finished.
- duration (str) – Build duration. It might not correspond to
finished_at
-started_at
if the build was restarted at a later point. - job_ids (list(int)) – List of job IDs in the build matrix.
- pull_request (bool) – Whether or not the build comes from a pull request.
- commit (Commit) –
Commit
information.
-
class
travispy.entities.
Broadcast
(session)[source]¶ Bases:
travispy.entities._entity.Entity
Variables: message (str) – Broadcast message.
-
class
travispy.entities.
Build
(session)[source]¶ Bases:
travispy.entities._restartable.Restartable
Variables: - repository_id (int) – Repository ID.
- commit_id (str) – Commit ID.
- number (str) – Build number.
- pull_request (bool) – Whether or not the build comes from a pull request.
- pull_request_title (str) – PR title if
pull_request
isTrue
. - pull_request_number (str) – PR number if
pull_request
isTrue
. - config (dict) – Build config (secure values and ssh key removed). It comes from
.travis.yml
file. - started_at (str) – Time the build was started.
- finished_at (str) – Time the build finished.
- duration (str) – Build duration. It might not correspond to
finished_at
-started_at
if the build was restarted at a later point. - job_ids (list(int)) – List of job IDs in the build matrix.
- jobs (list(Job)) – List of
Job
in the build matrix. - commit (Commit) –
Commit
information.
-
class
travispy.entities.
Commit
(session)[source]¶ Bases:
travispy.entities._entity.Entity
There is no API endpoint for resolving commits, however commit data might be included in other API entities, like
Build
orJob
.Variables: - sha (str) – Commit SHA.
- branch (str) – Branch the commit is on.
- message (str) – Commit message.
- committed_at (str) – Commit date.
- author_name (str) – Author name.
- author_email (str) – Author email.
- committer_name (str) – Committer name.
- committer_email (str) – Committer email.
- compare_url (str) – Link to diff on GitHub.
- tag (str) – Tag name.
- pull_request_number (int) – Pull request number.
-
class
travispy.entities.
Hook
(session)[source]¶ Bases:
travispy.entities._entity.Entity
Variables: - name (str) – Hook name.
- description (str) – Hook description.
- owner_name (str) – Owner name.
- active (str) – Whether or not the hook is active.
- private (str) – Whether or not the hook is private.
- admin (bool) – Whether or not current user has administrator privileges.
-
class
travispy.entities.
Job
(session)[source]¶ Bases:
travispy.entities._restartable.Restartable
Variables: - build_id (int) – Build ID.
- repository_id (int) – Repository ID.
- commit_id (int) – Commit ID.
- log_id (int) – Log ID.
- number (str) – Job number.
- config (dict) – Job config (secure values and ssh key removed). It comes from
.travis.yml
file. - started_at (str) – Time the job was started.
- finished_at (str) – Time the job finished.
- duration (str) – Job duration. It might not correspond to
finished_at
-started_at
if the job was restarted at a later point. - queue (str) – Job queue.
- allow_failure (bool) – Whether or not the job state influences build state.
- annotation_ids (list(int)) – List of annotation IDs.
- commit (Commit) –
Commit
information.
-
class
travispy.entities.
Log
(session)[source]¶ Bases:
travispy.entities._entity.Entity
Variables: - job_id (int) – Jod ID.
- type (str) –
-
body
¶ Return type: str Returns: The raw log text fetched on demand.
-
class
travispy.entities.
Repo
(session)[source]¶ Bases:
travispy.entities._stateful.Stateful
Variables: - slug (str) – Repository slug.
- description (str) – Description on GitHub.
- last_build_id (int) – Build ID of the last executed build.
- last_build_number (str) – Build number of the last executed build.
- last_build_state (str) – Build state of the last executed build.
- last_build_duration (str) – Build duration of the last executed build.
- last_build_started_at (str) – Build started at of the last executed build.
- last_build_finished_at (str) – Build finished at of the last executed build.
- github_language (str) – Language on GitHub.
- active (bool) – Whether or not the repository is active on Travis CI.
-
disable
()[source]¶ Disable Travis CI for the repository.
Return type: bool Returns: True
if API call was successful.False
if API call was unsuccessful.
-
enable
()[source]¶ Enable Travis CI for the repository
Return type: bool Returns: True
if API call was successfulFalse
if API call was unsuccessful
-
class
travispy.entities.
User
(session)[source]¶ Bases:
travispy.entities._entity.Entity
Variables: - login (str) – User login on GitHub.
- name (str) – User name on GitHub.
- email (str) – Primary email address on GitHub.
- gravatar_id (str) – Avatar ID.
- is_syncing (bool) – Whether or not user account is currently being synced.
- synced_at (str) – Last synced at.
- correct_scopes (bool) – Whether or not GitHub token has the correct scopes.
- channels (str) – Pusher channels for this user.
- created_at (str) – When account was created.
- locale (str) – User main locale.
Contribute¶
TravisPy is under development, so if you want to join the team, you are welcome.
- Feel free to open issues related to bugs or ideas.
- If you are a developer:
- Fork TravisPy before making any changes.
- Write tests.
- Create a Pull Request so changes can be merged.
License¶
TravisPy is licensed under GPL v3.0 license.