Interface¶

class GogsApi(base_url, session=None)¶

A Gogs client, serving as a wrapper around the Gogs HTTP API.

__init__(base_url, session=None)¶

Parameters:	base_url (str) – the URL of the Gogs server to communicate with. Should be given with the https protocol session (requests.Session) – a requests session instance

valid_authentication(auth)¶

Returns whether auth is valid

Parameters:	auth (auth.Authentication) – authentication object
Returns:	whether the provided authentication is valid
Return type:	bool
Raises:	NetworkFailure – if there is an error communicating with the server

authenticated_user(auth)¶

Returns the user authenticated by auth

Parameters:	auth (auth.Authentication) – authentication for user to retrieve
Returns:	user authenticated by the provided authentication
Return type:	GogsUser
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

get_tokens(auth, username=None)¶

Returns the tokens owned by the specified user. If no user is specified, uses the user authenticated by auth.

Parameters:	auth (auth.Authentication) – authentication for user to retrieve. Must be a username-password authentication, due to a restriction of the Gogs API username (str) – username of owner of tokens
Returns:	list of tokens
Return type:	List[Token]
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

create_token(auth, name, username=None)¶

Creates a new token with the specified name for the specified user. If no user is specified, uses user authenticated by auth.

Parameters:	auth (auth.Authentication) – authentication for user to retrieve. Must be a username-password authentication, due to a restriction of the Gogs API name (str) – name of new token username (str) – username of owner of new token
Returns:	new token representation
Return type:	Token
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

ensure_token(auth, name, username=None)¶

Ensures the existence of a token with the specified name for the specified user. Creates a new token if none exists. If no user is specified, uses user authenticated by auth.

Parameters:	auth (auth.Authentication) – authentication for user to retrieve. Must be a username-password authentication, due to a restriction of the Gogs API name (str) – name of new token username (str) – username of owner of new token
Returns:	token representation
Return type:	Token
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

create_repo(auth, name, description=None, private=False, auto_init=False, gitignore_templates=None, license_template=None, readme_template=None, organization=None)¶

Creates a new repository, and returns the created repository.

Parameters:	auth (auth.Authentication) – authentication object name (str) – name of the repository to create description (str) – description of the repository to create private (bool) – whether the create repository should be private auto_init (bool) – whether the created repository should be auto-initialized with an initial commit gitignore_templates (list[str]) – collection of .gitignore templates to apply license_template (str) – license template to apply readme_template (str) – README template to apply organization (str) – organization under which repository is created
Returns:	a representation of the created repository
Return type:	GogsRepo
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

repo_exists(auth, username, repo_name)¶

Returns whether a repository with name repo_name owned by the user with username username exists.

Parameters:	auth (auth.Authentication) – authentication object username (str) – username of owner of repository repo_name (str) – name of repository
Returns:	whether the repository exists
Return type:	bool
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

get_repo(auth, username, repo_name)¶

Returns a the repository with name repo_name owned by the user with username username.

Parameters:	auth (auth.Authentication) – authentication object username (str) – username of owner of repository repo_name (str) – name of repository
Returns:	a representation of the retrieved repository
Return type:	GogsRepo
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

get_user_repos(auth, username)¶

Returns the repositories owned by the user with username username.

Parameters:	auth (auth.Authentication) – authentication object username (str) – username of owner of repository
Returns:	a list of repositories
Return type:	List[GogsRepo]
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

get_branch(auth, username, repo_name, branch_name)¶

Returns the branch with name branch_name in the repository with name repo_name owned by the user with username username.

Parameters:	auth (auth.Authentication) – authentication object username (str) – username of owner of repository containing the branch repo_name (str) – name of the repository with the branch branch_name (str) – name of the branch to return
Returns:	a branch
Return type:	GogsBranch
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

get_branches(auth, username, repo_name)¶

Returns the branches in the repository with name repo_name owned by the user with username username.

Parameters:	auth (auth.Authentication) – authentication object username (str) – username of owner of repository containing the branch repo_name (str) – name of the repository with the branch
Returns:	a list of branches
Return type:	List[GogsBranch]
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

delete_repo(auth, username, repo_name)¶

Deletes the repository with name repo_name owned by the user with username username.

Parameters:	auth (auth.Authentication) – authentication object username (str) – username of owner of repository to delete repo_name (str) – name of repository to delete
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

migrate_repo(auth, clone_addr, uid, repo_name, auth_username=None, auth_password=None, mirror=False, private=False, description=None)¶

Migrate a repository from another Git hosting source for the authenticated user.

Parameters:	auth (auth.Authentication) – authentication object clone_addr (str) – Remote Git address (HTTP/HTTPS URL or local path) uid (int) – user ID of repository owner repo_name (str) – Repository name mirror (bool) – Repository will be a mirror. Default is false private (bool) – Repository will be private. Default is false description (str) – Repository description
Returns:	a representation of the migrated repository
Return type:	GogsRepo
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

create_user(auth, login_name, username, email, password, send_notify=False)¶

Creates a new user, and returns the created user.

Parameters:	auth (auth.Authentication) – authentication object, must be admin-level login_name (str) – login name for created user username (str) – username for created user email (str) – email address for created user password (str) – password for created user send_notify (bool) – whether a notification email should be sent upon creation
Returns:	a representation of the created user
Return type:	GogsUser
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

user_exists(username)¶

Returns whether a user with username username exists.

Parameters:	username (str) – username of user
Returns:	whether a user with the specified username exists
Return type:	bool
Raises:	NetworkFailure – if there is an error communicating with the server
Returns:

search_users(username_keyword, limit=10)¶

Searches for users whose username matches username_keyword, and returns a list of matched users.

Parameters:	username_keyword (str) – keyword to search with limit (int) – maximum number of returned users
Returns:	a list of matched users
Return type:	List[GogsUser]
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

get_user(auth, username)¶

Returns a representing the user with username username.

Parameters:	auth (auth.Authentication) – authentication object, can be None username (str) – username of user to get
Returns:	the retrieved user
Return type:	GogsUser
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

update_user(auth, username, update)¶

Updates the user with username username according to update.

Parameters:	auth (auth.Authentication) – authentication object, must be admin-level username (str) – username of user to update update (GogsUserUpdate) – a GogsUserUpdate object describing the requested update
Returns:	the updated user
Return type:	GogsUser
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

delete_user(auth, username)¶

Deletes the user with username username. Should only be called if the to-be-deleted user has no repositories.

Parameters:	auth (auth.Authentication) – authentication object, must be admin-level username (str) – username of user to delete

get_repo_hooks(auth, username, repo_name)¶

Returns all hooks of repository with name repo_name owned by the user with username username.

Parameters:	auth (auth.Authentication) – authentication object username (str) – username of owner of repository repo_name (str) – name of repository
Returns:	a list of hooks for the specified repository
Return type:	List[GogsRepo.Hooks]
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

create_hook(auth, repo_name, hook_type, config, events=None, organization=None, active=False)¶

Creates a new hook, and returns the created hook.

Parameters:	auth (auth.Authentication) – authentication object, must be admin-level repo_name (str) – the name of the repo for which we create the hook hook_type (str) – The type of webhook, either “gogs” or “slack” config (dict) – Settings for this hook (possible keys are "url", "content_type", "secret") events (list) – Determines what events the hook is triggered for. Default: [“push”] organization (str) – Organization of the repo active (bool) – Determines whether the hook is actually triggered on pushes. Default is false
Returns:	a representation of the created hook
Return type:	GogsRepo.Hook
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

update_hook(auth, repo_name, hook_id, update, organization=None)¶

Updates hook with id hook_id according to update.

Parameters:	auth (auth.Authentication) – authentication object repo_name (str) – repo of the hook to update hook_id (int) – id of the hook to update update (GogsHookUpdate) – a GogsHookUpdate object describing the requested update organization (str) – name of associated organization, if applicable
Returns:	the updated hook
Return type:	GogsRepo.Hook
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

delete_hook(auth, username, repo_name, hook_id)¶

Deletes the hook with id hook_id for repo with name repo_name owned by the user with username username.

Parameters:	auth (auth.Authentication) – authentication object username (str) – username of owner of repository repo_name (str) – name of repository of hook to delete hook_id (int) – id of hook to delete
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

create_organization(auth, owner_name, org_name, full_name=None, description=None, website=None, location=None)¶

Creates a new organization, and returns the created organization.

Parameters:	auth (auth.Authentication) – authentication object, must be admin-level owner_name (str) – Username of organization owner org_name (str) – Organization name full_name (str) – Full name of organization description (str) – Description of the organization website (str) – Official website location (str) – Organization location
Returns:	a representation of the created organization
Return type:	GogsOrg
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

create_organization_team(auth, org_name, name, description=None, permission='read')¶

Creates a new team of the organization.

Parameters:	auth (auth.Authentication) – authentication object, must be admin-level org_name (str) – Organization user name name (str) – Full name of the team description (str) – Description of the team permission (str) – Team permission, can be read, write or admin, default is read
Returns:	a representation of the created team
Return type:	GogsTeam
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

add_team_membership(auth, team_id, username)¶

Add user to team.

Parameters:	auth (auth.Authentication) – authentication object, must be admin-level team_id (str) – Team’s id username (str) – Username of the user to be added to team
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

remove_team_membership(auth, team_id, username)¶

Remove user from team.

Parameters:	auth (auth.Authentication) – authentication object, must be admin-level team_id (str) – Team’s id username (str) – Username of the user to be removed from the team
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

add_repo_to_team(auth, team_id, repo_name)¶

Add or update repo from team.

Parameters:	auth (auth.Authentication) – authentication object, must be admin-level team_id (str) – Team’s id repo_name (str) – Name of the repo to be added to the team
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

remove_repo_from_team(auth, team_id, repo_name)¶

Remove repo from team.

Parameters:	auth (auth.Authentication) – authentication object, must be admin-level team_id (str) – Team’s id repo_name (str) – Name of the repo to be removed from the team
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

list_deploy_keys(auth, username, repo_name)¶

List deploy keys for the specified repo.

Parameters:	auth (auth.Authentication) – authentication object username (str) – username of owner of repository repo_name (str) – the name of the repo
Returns:	a list of deploy keys for the repo
Return type:	List[GogsRepo.DeployKey]
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

get_deploy_key(auth, username, repo_name, key_id)¶

Get a deploy key for the specified repo.

Parameters:	auth (auth.Authentication) – authentication object username (str) – username of owner of repository repo_name (str) – the name of the repo key_id (int) – the id of the key
Returns:	the deploy key
Return type:	GogsRepo.DeployKey
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

add_deploy_key(auth, username, repo_name, title, key_content)¶

Add a deploy key to the specified repo.

Parameters:	auth (auth.Authentication) – authentication object username (str) – username of owner of repository repo_name (str) – the name of the repo title (str) – title of the key to add key_content (str) – content of the key to add
Returns:	a representation of the added deploy key
Return type:	GogsRepo.DeployKey
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

delete_deploy_key(auth, username, repo_name, key_id)¶

Remove deploy key for the specified repo.

Parameters:	auth (auth.Authentication) – authentication object username (str) – username of owner of repository repo_name (str) – the name of the repo key_id (int) – the id of the key
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

delete(path, auth=None, **kwargs)¶

Manually make a DELETE request.

Parameters:	path (str) – relative url of the request (e.g. /users/username) auth (auth.Authentication) – authentication object dict (kwargs) – Extra arguments for the request, as supported by the requests library.
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

get(path, auth=None, **kwargs)¶

Manually make a GET request.

Parameters:	path (str) – relative url of the request (e.g. /users/username) auth (auth.Authentication) – authentication object dict (kwargs) – Extra arguments for the request, as supported by the requests library.
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

patch(path, auth=None, **kwargs)¶

Manually make a PATCH request.

Parameters:	path (str) – relative url of the request (e.g. /users/username) auth (auth.Authentication) – authentication object dict (kwargs) – Extra arguments for the request, as supported by the requests library.
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

post(path, auth=None, **kwargs)¶

Manually make a POST request.

Parameters:	path (str) – relative url of the request (e.g. /users/username) auth (auth.Authentication) – authentication object dict (kwargs) – Extra arguments for the request, as supported by the requests library.
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

put(path, auth=None, **kwargs)¶

Manually make a PUT request.

Parameters:	path (str) – relative url of the request (e.g. /users/username) auth (auth.Authentication) – authentication object dict (kwargs) – Extra arguments for the request, as supported by the requests library.
Raises:	NetworkFailure – if there is an error communicating with the server ApiFailure – if the request cannot be serviced

exception ApiFailure(message, status_code)¶

Raised to signal a failed request

message¶

An error message explaining why the request failed.

Type:	str

status_code¶

The HTTP status code of the response to the failed request

Type:	int

exception NetworkFailure(cause=None)¶

Raised to signal a network-level failure

cause¶

The exception causing the network failure

Type:	Exception