{"id":1292,"library":"atlassian-python-api","title":"Atlassian Python API Wrapper","description":"The `atlassian-python-api` library provides a comprehensive and convenient Python wrapper for interacting with various Atlassian products, including Jira, Confluence, Bitbucket, Crowd, Service Desk, Xray, and Bamboo. It supports both Atlassian Cloud and Server/Data Center instances by leveraging their official REST APIs, along with some additional private methods and protocols. Currently at version 4.0.7, the library maintains an active development and release cadence, frequently adding new features, bug fixes, and adjustments for evolving Atlassian APIs.","status":"active","version":"4.0.7","language":"en","source_language":"en","source_url":"https://github.com/atlassian-api/atlassian-python-api","tags":["Atlassian","Jira","Confluence","Bitbucket","API","wrapper","automation"],"install":[{"cmd":"pip install atlassian-python-api","lang":"bash","label":"Install stable version"},{"cmd":"pip install atlassian-python-api[kerberos]","lang":"bash","label":"Install with Kerberos authentication support"}],"dependencies":[{"reason":"HTML parsing for certain operations","package":"beautifulsoup4","optional":false},{"reason":"Decorator for marking deprecated functions","package":"deprecated","optional":false},{"reason":"JSON query language for Python","package":"jmespath","optional":false},{"reason":"OAuth 1.0/2.0 implementation","package":"oauthlib","optional":false},{"reason":"HTTP library","package":"requests","optional":false},{"reason":"OAuth support for Requests","package":"requests_oauthlib","optional":false},{"reason":"Backports of new typing features","package":"typing-extensions","optional":false},{"reason":"Kerberos authentication support","package":"requests-kerberos","optional":true}],"imports":[{"symbol":"Jira","correct":"from atlassian import Jira"},{"symbol":"Confluence","correct":"from atlassian import Confluence"},{"symbol":"Bitbucket","correct":"from atlassian import Bitbucket"},{"note":"For Jira Cloud, prefer `JiraCloud` for specific cloud features, though `Jira` often works for basic operations with cloud=True parameter.","wrong":"from atlassian.jira import Jira","symbol":"Jira","correct":"from atlassian.jira import JiraCloud"}],"quickstart":{"code":"import os\nfrom atlassian import Jira\n\n# For Jira Cloud, use API Token authentication.\n# Generate an API token at: https://id.atlassian.com/manage-profile/security/api-tokens\nJIRA_URL = os.environ.get('ATLASSIAN_JIRA_URL', 'https://your-domain.atlassian.net')\nJIRA_EMAIL = os.environ.get('ATLASSIAN_JIRA_EMAIL', 'your_email@example.com')\nJIRA_API_TOKEN = os.environ.get('ATLASSIAN_JIRA_API_TOKEN', 'YOUR_API_TOKEN')\n\nif not all([JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN]):\n    print(\"Please set ATLASSIAN_JIRA_URL, ATLASSIAN_JIRA_EMAIL, and ATLASSIAN_JIRA_API_TOKEN environment variables.\")\nelse:\n    try:\n        jira = Jira(\n            url=JIRA_URL,\n            username=JIRA_EMAIL,\n            password=JIRA_API_TOKEN, # API token for Cloud\n            cloud=True # Important for Jira Cloud\n        )\n\n        # Test connection by getting current user\n        current_user = jira.myself()\n        print(f\"Successfully connected to Jira. Current user: {current_user['displayName']}\")\n\n        # Example: Get all projects\n        projects = jira.get_all_projects(start=0, limit=5)\n        print(f\"First 5 projects: {[p['name'] for p in projects]}\")\n\n    except Exception as e:\n        print(f\"Error connecting to Jira or fetching data: {e}\")","lang":"python","description":"This quickstart demonstrates how to connect to Jira Cloud using an API token, which is the recommended authentication method for cloud instances. It then retrieves the current user's display name and lists the first five available projects to verify the connection and basic functionality. Environment variables are used for sensitive credentials."},"warnings":[{"fix":"Migrate your project to Python 3.9 or newer. Python 3.9+ is required for version 4.0.0 and above.","message":"Version 4.0.0 removed Python 2 support. Projects using `atlassian-python-api` with Python 2 will break upon upgrade.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"For Atlassian Cloud, use API tokens for basic authentication (username is email, password is API token) or OAuth 2.0. Generate API tokens from your Atlassian account security settings.","message":"Atlassian Cloud APIs no longer support basic authentication with a username and password (deprecated since June 2019). Attempting to use a password for Cloud authentication will result in an 'invalid credentials' error.","severity":"breaking","affected_versions":"All versions interacting with Atlassian Cloud APIs after June 2019"},{"fix":"Always consult the `atlassian-python-api` documentation for the specific product (Jira, Confluence, Bitbucket, etc.) and deployment type (Cloud or Server/DC) you are targeting to ensure correct API calls and authentication parameters. Some modules, like Confluence, have dedicated `ConfluenceCloud` and `ConfluenceServer` classes.","message":"There are significant API and authentication differences between Atlassian Cloud and Server/Data Center instances. This includes authentication methods (API Token for Cloud vs. username/password/PAT for Server) and content ID formats (UUID strings for Cloud vs. numeric IDs for Server).","severity":"gotcha","affected_versions":"All versions"},{"fix":"For `attach_file()`, ensure unique filenames or implement logic to handle existing attachments if new revisions are expected. For `download_attachments_from_page`, explicitly decode the returned bytes to text if needed (e.g., `.decode('utf-8')`).","message":"The `attach_file()` method in Confluence may not create a new revision when re-uploading a file with the same name, potentially leading to errors. Additionally, `download_attachments_from_page` in version 4.0.0 started returning bytes instead of text, which might require changes in how file content is handled.","severity":"gotcha","affected_versions":">=4.0.0 for `download_attachments_from_page`; various for `attach_file()`"},{"fix":"Ensure you are using the latest `atlassian-python-api` version (4.0.0 or later added `search/jql` support) and review your JQL search implementations to align with Atlassian's updated API guidelines.","message":"Atlassian itself is deprecating some Jira JQL search API endpoints (effective May 1, 2025). While `atlassian-python-api` has updated to support the new `search/jql` endpoint, older scripts or direct API calls might be affected.","severity":"deprecated","affected_versions":"Scripts using older Jira JQL search APIs, potentially versions of `atlassian-python-api` prior to those implementing the new `search/jql` endpoint (e.g., pre-4.0.0)."}],"env_vars":null,"last_verified":"2026-04-08T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}