Welcome to Bitbucket-API’s documentation!¶
Installation¶
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.
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 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.
-
username
¶ Return your repository’s username.
-
issue
Module¶
-
class
bitbucket.issue.
Issue
(bitbucket, issue_id=None)[source]¶ This class provide issue-related methods to Bitbucket objects.
-
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).
-
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.
-
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.
-
repository
Module¶
-
class
bitbucket.repository.
Repository
(bitbucket)[source]¶ This class provide repository-related methods to Bitbucket objects.
-
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.
-
service
Module¶
-
class
bitbucket.service.
Service
(bitbucket)[source]¶ This class provide services-related methods to Bitbucket objects.
-
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’).
-
ssh
Module¶
Subpackages¶
bitbucket.tests Package¶
tests
Package¶
public
Module¶
-
class
bitbucket.tests.public.
AnonymousBitbucketTest
(methodName='runTest')[source]¶ Bases:
unittest.case.TestCase
Bitbucket test base class.
-
class
bitbucket.tests.public.
BitbucketAnnonymousMethodsTest
(methodName='runTest')[source]¶ Bases:
bitbucket.tests.public.AnonymousBitbucketTest
Test Bitbucket annonymous methods.
-
class
bitbucket.tests.public.
BitbucketUtilitiesTest
(methodName='runTest')[source]¶ Bases:
bitbucket.tests.public.AnonymousBitbucketTest
Test Bitbucket utilities functions.
Subpackages¶
bitbucket.tests.private Package¶
private
Package¶issue
Module¶issue_comment
Module¶-
class
bitbucket.tests.private.issue_comment.
IssueCommentAuthenticatedMethodsTest
(methodName='runTest')[source]¶ Bases:
bitbucket.tests.private.private.AuthenticatedBitbucketTest
Testing bitbucket.issue.comments methods.
private
Module¶-
class
bitbucket.tests.private.private.
AuthenticatedBitbucketTest
(methodName='runTest')[source]¶ Bases:
unittest.case.TestCase
Bitbucket test base class for authenticated methods.
-
class
bitbucket.tests.private.private.
BitbucketAuthenticatedMethodsTest
(methodName='runTest')[source]¶ Bases:
bitbucket.tests.private.private.AuthenticatedBitbucketTest
Testing Bitbucket annonymous methods.
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.
-
class
bitbucket.tests.private.repository.
RepositoryAuthenticatedMethodsTest
(methodName='runTest')[source]¶ Bases:
bitbucket.tests.private.private.AuthenticatedBitbucketTest
Testing bitbucket.repository methods.
service
Module¶-
class
bitbucket.tests.private.service.
ServiceAuthenticatedMethodsTest
(methodName='runTest')[source]¶ Bases:
bitbucket.tests.private.private.AuthenticatedBitbucketTest
Testing bitbucket.service methods.
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.