Welcome to Bitbucket-API’s documentation!

Installation

Pip

Installing Bitbucket-API is simple with pip:

pip install Bitbucket-API

Get the Code & contribute

Bitbucket-API is hosted on GitHub, where the code is always available.

You can either clone the public repository:

git clone git@github.com:Sheeprider/BitBucket-api.git

Download the tarball:

curl -OL https://github.com/Sheeprider/BitBucket-api/tarball/master

Or, download the zipball:

curl -OL https://github.com/Sheeprider/Bitbucket-API/zipball/master

Test

Run public tests:

site-packages$> python -m bitbucket.tests.public

Run private tests. Require USERNAME and PASSWORD or USERNAME, CONSUMER_KEY and CONSUMER_SECRET in bitbucket/tests/private/settings.py:

site-packages$> python -m bitbucket.tests.private

Usage

Public

You can access any public repository on Bitbucket, but some actions won’t be available without credentials.

>>> from bitbucket.bitbucket import Bitbucket
>>> bb = Bitbucket(USERNAME, repo_name_or_slug='public_slug')
>>> success, result = bb.repository.delete()
>>> print success
False

Private

With the correct credentials you can access private repositories on Bitbucket.

>>> from bitbucket.bitbucket import Bitbucket
>>> bb = Bitbucket(USERNAME, PASSWORD, 'private_slug')
>>> success, result = bb.repository.get()
>>> print success, result
True {...}

Examples

Connect using Oauth

>>> import webbrowser
>>> from bitbucket.bitbucket import Bitbucket
>>> bb = Bitbucket(USERNAME)
>>> # First time we need to open up a browser to enter the verifier
>>> if not OAUTH_ACCESS_TOKEN and not OAUTH_ACCESS_TOKEN_SECRET:
>>>     bb.authorize(CONSUMER_KEY, CONSUMER_SECRET, 'http://localhost/')
>>>     # open a webbrowser and get the token
>>>     webbrowser.open(bb.url('AUTHENTICATE', token=bb.access_token))
>>>     # Copy the verifier field from the URL in the browser into the console
>>>     oauth_verifier = raw_input('Enter verifier from url [oauth_verifier]')
>>>     bb.verify(oauth_verifier)
>>>     OAUTH_ACCESS_TOKEN = bb.access_token
>>>     OAUTH_ACCESS_TOKEN_SECRET = bb.access_token_secret
>>> else:
>>>     bb.authorize(CONSUMER_KEY, CONSUMER_SECRET, 'http://localhost/', OAUTH_ACCESS_TOKEN, OAUTH_ACCESS_TOKEN_SECRET)

List all repositories for a user (from @matthew-campbell):

>>> from bitbucket.bitbucket import Bitbucket
>>> bb = Bitbucket(USERNAME, PASSWORD)
>>> success, repositories = bb.repository.all()
>>> for repo in sorted(repositories):
>>>     p = '+'
>>>     if repo['is_private']:
>>>         p ='-'
>>>     print('({}){}, {}, {}'.format(p, repo['name'], repo['last_updated'], repo['scm']))
>>> print('Total {}'.format(len(repositories)))

bitbucket Package

bitbucket Package

Bitbucket has a REST API publicly available, this package provide methods to interact with it. It allows you to access repositories and perform various actions on them.

Various usages :

from bitbucket.bitbucket import Bitbucket

# Access a public repository
bb = Bitbucket(USERNAME, repo_name_or_slug="public_repository")

# Access a private repository
bb = Bitbucket(USERNAME, PASSWORD, repo_name_or_slug="private_repository")

# Access a private repository through oauth
bb = Bitbucket(USERNAME, repo_name_or_slug="public_repository")
bb.authorize(CONSUMER_KEY, CONSUMER_SECRET, 'http://localhost/')


# Access your working repository
success, result = bb.repository.get()

# Create a repository, and define it as your working repository
success, result = bb.repository.create("repository_slug")
bb.repo_slug = "repository_slug"

# Update your working repository
success, result = bb.repository.update(description='new description')

# Delete a repository
success, result = bb.repository.delete("repository_slug")

# Download a repository as an archive
success, archive_path = bb.repository.archive()

# Access user informations
success, result = bb.get_user(username=USERNAME)

# Access tags and branches
success, result = bb.get_tags()
success, result = bb.get_branches()

# Access, create, update or delete a service (hook)
success, result = bb.service.get(service_id=SERVICE_ID)
success, result = bb.service.create(service=u'POST', URL='http://httpbin.org/')
success, result = bb.service.update(service_id=SERVICE_ID, URL='http://google.com')
success, result = bb.service.delete(service_id=SERVICE_ID)

# Access, create or delete an SSH key
success, result = bb.ssh.get(key_id=SSH_ID)
success, result = bb.ssh.create(key=r'ssh-rsa a1b2c3d4e5', label=u'my key')
success, result = bb.ssh.delete(key_id=SSH_ID)

# Access, create, update or delete an issue
success, result = bb.issue.get(issue_id=ISSUE_ID)
success, result = bb.issue.create(
    title=u'Issue title',
    content=u'Issue content',
    responsible=bb.username,
    status=u'new',
    kind=u'bug')
success, result = bb.issue.update(issue_id=ISSUE_ID, content='New content')
success, result = bb.issue.delete(issue_id=ISSUE_ID)

# Access, create, update or delete an issue comment
success, result = bb.issue.comment.get(comment_id=COMMENT_ID)
success, result = bb.issue.comment.create(content='Content')
success, result = bb.issue.comment.update(
    comment_id=COMMENT_ID,
    content='New content')
success, result = bb.issue.comment.delete(comment_id=COMMENT_ID)

Bitbucket Module

class bitbucket.bitbucket.Bitbucket(username='', password='', repo_name_or_slug='')[source]

This class lets you interact with the bitbucket public API.

auth

Return credentials for current Bitbucket user.

authorize(consumer_key, consumer_secret, callback_url=None, access_token=None, access_token_secret=None)[source]

Call this with your consumer key, secret and callback URL, to generate a token for verification.

dispatch(method, url, auth=None, params=None, **kwargs)[source]

Send HTTP request, with given method, credentials and data to the given URL, and return the success and the result on success.

finalize_oauth(access_token, access_token_secret)[source]

Called internally once auth process is complete.

get_branches(repo_slug=None)[source]

Get a single repository on Bitbucket and return its branches.

get_privileges()[source]

Get privledges for this user.

get_tags(repo_slug=None)[source]

Get a single repository on Bitbucket and return its tags.

get_user(username=None)[source]

Returns user informations. If username is not defined, tries to return own informations.

password

Return your repository’s password.

repo_slug

Return your repository’s slug name.

url(action, **kwargs)[source]

Construct and return the URL for a specific API service.

username

Return your repository’s username.

verify(verifier, consumer_key=None, consumer_secret=None, access_token=None, access_token_secret=None)[source]

After converting the token into verifier, call this to finalize the authorization.

issue Module

class bitbucket.issue.Issue(bitbucket, issue_id=None)[source]

This class provide issue-related methods to Bitbucket objects.

all(repo_slug=None, params=None)[source]

Get issues from one of your repositories.

create(repo_slug=None, **kwargs)[source]

Add an issue to one of your repositories. Each issue require a different set of attributes, you can pass them as keyword arguments (attributename=’attributevalue’). Attributes are:

  • title: The title of the new issue.
  • content: The content of the new issue.
  • component: The component associated with the issue.
  • milestone: The milestone associated with the issue.
  • version: The version associated with the issue.
  • responsible: The username of the person responsible for the issue.
  • status: The status of the issue (new, open, resolved, on hold, invalid, duplicate, or wontfix).
  • kind: The kind of issue (bug, enhancement, or proposal).
delete(issue_id, repo_slug=None)[source]

Delete an issue from one of your repositories.

get(issue_id, repo_slug=None)[source]

Get an issue from one of your repositories.

issue_id

Your repository slug name.

update(issue_id, repo_slug=None, **kwargs)[source]

Update an issue to one of your repositories. Each issue require a different set of attributes, you can pass them as keyword arguments (attributename=’attributevalue’). Attributes are:

  • title: The title of the new issue.
  • content: The content of the new issue.
  • component: The component associated with the issue.
  • milestone: The milestone associated with the issue.
  • version: The version associated with the issue.
  • responsible: The username of the person responsible for the issue.
  • status: The status of the issue (new, open, resolved, on hold, invalid, duplicate, or wontfix).
  • kind: The kind of issue (bug, enhancement, or proposal).

issue_comment Module

class bitbucket.issue_comment.IssueComment(issue)[source]

This class provide issue’s comments related methods to Bitbucket objects.

all(issue_id=None, repo_slug=None)[source]

Get issue comments from one of your repositories.

create(issue_id=None, repo_slug=None, **kwargs)[source]

Add an issue comment to one of your repositories. Each issue comment require only the content data field the system autopopulate the rest.

delete(comment_id, issue_id=None, repo_slug=None)[source]

Delete an issue from one of your repositories.

get(comment_id, issue_id=None, repo_slug=None)[source]

Get an issue from one of your repositories.

update(comment_id, issue_id=None, repo_slug=None, **kwargs)[source]

Update an issue comment in one of your repositories. Each issue comment require only the content data field the system autopopulate the rest.

repository Module

class bitbucket.repository.Repository(bitbucket)[source]

This class provide repository-related methods to Bitbucket objects.

all()[source]

Return own repositories.

archive(repo_slug=None, format='zip', prefix='')[source]

Get one of your repositories and compress it as an archive. Return the path of the archive.

format parameter is curently not supported.

create(repo_name, scm='git', private=True, **kwargs)[source]

Creates a new repository on own Bitbucket account and return it.

delete(repo_slug=None)[source]

Delete a repository on own Bitbucket account. Please use with caution as there is NO confimation and NO undo.

get(repo_slug=None)[source]

Get a single repository on Bitbucket and return it.

public(username=None)[source]

Returns all public repositories from an user. If username is not defined, tries to return own public repos.

update(repo_slug=None, **kwargs)[source]

Updates repository on own Bitbucket account and return it.

service Module

class bitbucket.service.Service(bitbucket)[source]

This class provide services-related methods to Bitbucket objects.

all(repo_slug=None)[source]

Get all services (hook) from one of your repositories.

create(service, repo_slug=None, **kwargs)[source]

Add a service (hook) to one of your repositories. Each type of service require a different set of additionnal fields, you can pass them as keyword arguments (fieldname=’fieldvalue’).

delete(service_id, repo_slug=None)[source]

Delete a service (hook) from one of your repositories. Please use with caution as there is NO confimation and NO undo.

get(service_id, repo_slug=None)[source]

Get a service (hook) from one of your repositories.

update(service_id, repo_slug=None, **kwargs)[source]

Update a service (hook) from one of your repositories.

ssh Module

class bitbucket.ssh.SSH(bitbucket)[source]

This class provide ssh-related methods to Bitbucket objects.

all()[source]

Get all ssh keys associated with your account.

create(key=None, label=None)[source]

Associate an ssh key with your account and return it.

delete(key_id=None)[source]

Delete one of the ssh keys associated with your account. Please use with caution as there is NO confimation and NO undo.

get(key_id=None)[source]

Get one of the ssh keys associated with your account.

Subpackages

bitbucket.tests Package

tests Package
public Module
class bitbucket.tests.public.AnonymousBitbucketTest(methodName='runTest')[source]

Bases: unittest.case.TestCase

Bitbucket test base class.

setUp()[source]

Create a new annonymous Bitbucket...

tearDown()[source]

Destroy the Bitbucket...

class bitbucket.tests.public.BitbucketAnnonymousMethodsTest(methodName='runTest')[source]

Bases: bitbucket.tests.public.AnonymousBitbucketTest

Test Bitbucket annonymous methods.

test_get_none_public_repos()[source]

Test public_repos on specific user.

test_get_none_user()[source]

Test get_user with no username.

test_get_public_repos()[source]

Test public_repos on specific user.

test_get_self_public_repos()[source]

Test public_repos on specific user.

test_get_self_user()[source]

Test get_user on self username.

test_get_user()[source]

Test get_user on specific user.

class bitbucket.tests.public.BitbucketUtilitiesTest(methodName='runTest')[source]

Bases: bitbucket.tests.public.AnonymousBitbucketTest

Test Bitbucket utilities functions.

test_auth()[source]
test_default_credential()[source]
test_dispatch_delete()[source]
test_dispatch_get()[source]
test_dispatch_post()[source]
test_dispatch_put()[source]
test_password()[source]
test_repo_slug()[source]
test_url_complex()[source]
test_url_simple()[source]
test_username()[source]
Subpackages
bitbucket.tests.private Package
private Package
issue Module
class bitbucket.tests.private.issue.IssueAuthenticatedMethodsTest(methodName='runTest')[source]

Bases: bitbucket.tests.private.private.AuthenticatedBitbucketTest

Testing bitbucket.issue methods.

test_CRUD()[source]

Test issue create/read/update/delete.

test_all()[source]

Test get all issues.

issue_comment Module
class bitbucket.tests.private.issue_comment.IssueCommentAuthenticatedMethodsTest(methodName='runTest')[source]

Bases: bitbucket.tests.private.private.AuthenticatedBitbucketTest

Testing bitbucket.issue.comments methods.

setUp()[source]

Add an issue to the test repository and save it’s id.

tearDown()[source]

Delete the issue.

test_CRUD()[source]

Test issue comment create/read/update/delete.

test_all()[source]

Test get all issue comments.

private Module
class bitbucket.tests.private.private.AuthenticatedBitbucketTest(methodName='runTest')[source]

Bases: unittest.case.TestCase

Bitbucket test base class for authenticated methods.

setUp()[source]

Creating a new authenticated Bitbucket...

tearDown()[source]

Destroying the Bitbucket...

class bitbucket.tests.private.private.BitbucketAuthenticatedMethodsTest(methodName='runTest')[source]

Bases: bitbucket.tests.private.private.AuthenticatedBitbucketTest

Testing Bitbucket annonymous methods.

test_get_branches()[source]

Test get_branches.

test_get_tags()[source]

Test get_tags.

repository Module
class bitbucket.tests.private.repository.ArchiveRepositoryAuthenticatedMethodsTest(methodName='runTest')[source]

Bases: bitbucket.tests.private.private.AuthenticatedBitbucketTest

Testing bitbucket.repository.archive method, which require custom setUp and tearDown methods.

test_archive require a commit to download the repository.

setUp()[source]

Clone the test repo locally, then add and push a commit.

tearDown()[source]

Delete the git folder.

test_archive()[source]

Test repository download as archive.

class bitbucket.tests.private.repository.RepositoryAuthenticatedMethodsTest(methodName='runTest')[source]

Bases: bitbucket.tests.private.private.AuthenticatedBitbucketTest

Testing bitbucket.repository methods.

test_all()[source]

Test get all repositories.

test_create()[source]

Test repository creation.

test_delete()[source]

Test repository deletion.

test_get()[source]

Test get a repository.

test_update()[source]

Test repository update.

bitbucket.tests.private.repository.skipUnlessHasGit(f)[source]

This decorator pass the test if git is not found.

service Module
class bitbucket.tests.private.service.ServiceAuthenticatedMethodsTest(methodName='runTest')[source]

Bases: bitbucket.tests.private.private.AuthenticatedBitbucketTest

Testing bitbucket.service methods.

test_CRUD()[source]

Test service create/read/update/delete.

test_all()[source]

Test get all services.

settings Module

Set USERNAME and PASSWORD or USERNAME, CONSUMER_KEY and CONSUMER_SECRET in bitbucket/tests/private/settings.py if you want to run tests for private methods.

ssh Module
class bitbucket.tests.private.ssh.SSHAuthenticatedMethodsTest(methodName='runTest')[source]

Bases: bitbucket.tests.private.private.AuthenticatedBitbucketTest

Testing bitbucket.ssh methods.

test_CRUD()[source]

Test ssh create/read/delete.

test_all()[source]

Test get all sshs.

Indices and tables