• Stars
    star
    280
  • Rank 147,492 (Top 3 %)
  • Language
    Python
  • License
    MIT License
  • Created almost 10 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Official Python client library for the Asana API v1

asana Build PyPi Version

Python client library for Asana.


✨ Try a preview of our new python client library: python-asana-preview


Authentication

Personal Access Token

Create a client using your Asana Personal Access Token:

client = asana.Client.access_token('PERSONAL_ACCESS_TOKEN')

OAuth 2

Asana supports OAuth 2. asana handles some of the details of the OAuth flow for you.

Create a client using your OAuth Client ID and secret:

client = asana.Client.oauth(
  client_id='ASANA_CLIENT_ID',
  client_secret='ASANA_CLIENT_SECRET',
  redirect_uri='https://yourapp.com/auth/asana/callback'
)

Redirect the user to the authorization URL obtained from the client's session object:

(url, state) = client.session.authorization_url()

When the user is redirected back to your callback, check the state URL parameter matches, then pass the code parameter to obtain a bearer token:

if request.params['state'] == state:
  token = client.session.fetch_token(code=request.params['code'])
  # ...
else:
  # error! possible CSRF attack

Note: if you're writing a non-browser-based application (e.x. a command line tool) you can use the special redirect URI urn:ietf:wg:oauth:2.0:oob to prompt the user to copy and paste the code into the application.

Usage

The client's methods are divided into several resources: attachments, events, jobs, portfolios, portfolio_memberships, projects, project_memberships, stories, tags, tasks, teams, users, user_task_lists, and workspaces.

Methods that return a single object return that object directly:

me = client.users.get_user('me')
print(f'Hello {me['name']}')

workspace_id = me['workspaces'][0]['gid']
project = client.projects.create_in_workspace(workspace_id, { 'name': 'new project' })
print(f'Created project with id: {project['gid']}')

Methods that return multiple items (e.x. get_tasks, get_projects, get_portfolios, etc.) return a page iterator by default. See the "Collections" section.

See the gen folder for methods available for each resource.

Options

Various options can be set globally on the Client.DEFAULTS object, per-client on client.options, or per-request as additional named arguments. For example:

# global:
asana.Client.DEFAULT_OPTIONS['page_size'] = 100

# per-client:
client.options['page_size'] = 100

# per-request:
client.tasks.get_tasks({ 'project': 1234 }, page_size=100)

Available options

  • base_url (default: "https://app.asana.com/api/1.0"): API endpoint base URL to connect to
  • max_retries (default: 5): number to times to retry if API rate limit is reached or a server error occures. Rate limit retries delay until the rate limit expires, server errors exponentially backoff starting with a 1 second delay.
  • full_payload (default: False): return the entire JSON response instead of the 'data' propery (default for collection methods and events.get)
  • fields and expand: see API documentation

Collections (methods returning an array as its 'data' property):

  • iterator_type (default: "items"): specifies which type of iterator (or not) to return. Valid values are "items" and None.
  • item_limit (default: None): limits the number of items of a collection to return.
  • page_size (default: 50): limits the number of items per page to fetch at a time.
  • offset: offset token returned by previous calls to the same method (in response['next_page']['offset'])

Events:

  • poll_interval (default: 5): polling interval for getting new events via events.get_next and events.get_iterator
  • sync: sync token returned by previous calls to events.get (in response['sync'])

Asana Change Warnings

You will receive warning logs if performing requests that may be affected by a deprecation. The warning contains a link that explains the deprecation.

If you receive one of these warnings, you should:

  • Read about the deprecation.
  • Resolve sections of your code that would be affected by the deprecation.
  • Add the deprecation flag to your "asana-enable" header.

You can place it on the client for all requests, or place it on a single request.

client.headers={'asana-enable': 'string_ids'}
or
me = client.users.get_user('me', headers={'asana-enable': 'string_ids'})

If you would rather suppress these warnings, you can set

client.LOG_ASANA_CHANGE_WARNINGS = False

Collections

Items Iterator

By default, methods that return a collection of objects return an item iterator:

workspaces = client.workspaces.get_workspaces(item_limit=1)
print(next(workspaces))
print(next(workspaces)) # raises StopIteration if there are no more items

Or:

for workspace in client.workspaces.get_workspaces()
  print(workspace)

Raw API

You can also use the raw API to fetch a page at a time:

offset = None
while True:
  page = client.workspaces.get_workspaces(offset=offset, iterator_type=None, full_payload=True)
  print(page['data'])
  if 'next_page' in page and page['next_page']:
    offset = page['next_page']['offset']
  else:
    break

Contributing

Feel free to fork and submit pull requests for the code! Please follow the existing code as an example of style and make sure that all your code passes lint and tests.

Code generation

The specific Asana resource classes under gen (_Tag, _Workspace, _Task, etc) are generated code, hence they shouldn't be modified by hand.

Deployment

Repo Owners Only. Take the following steps to issue a new release of the library.

Automatic Deployment

Run deploy.py [major|minor|patch]. See deploy.py -h for additional info.

Manual Deployment

  1. Merge in the desired changes into the master branch and commit them.
  2. Clone the repo, work on master.
  3. Edit package version in asana/__init__.py and ./VERSION to indicate the semantic version change.
  4. Commit the change
  5. Tag the commit with v plus the same version number you set in the file. git tag v1.2.3
  6. Push changes to origin, including tags: git push origin master --tags

GitHub Actions will automatically build and deploy the tagged release to PyPI.

More Repositories

1

Drawsana

An open source library that lets your users draw on things - mark up images with text, shapes, etc.
Swift
645
star
2

typed-react

A binding layer between React and TypeScript
TypeScript
373
star
3

kraken

Distributed Pubsub Server for Realtime Apps
Erlang
335
star
4

node-asana

Official node.js and browser JS client for the Asana API v1
JavaScript
249
star
5

Chrome-Extension-Example

Sample application illustrating use of the Asana API
JavaScript
232
star
6

php-asana

Official PHP client library for the Asana API v1
PHP
135
star
7

locheck

Validate iOS, Android, and Mac localizations. Find errors in .strings, .stringsdict, and strings.xml files.
Swift
97
star
8

bazels3cache

Small web server for a Bazel cache, proxies to S3; allows Bazel to work offline; async uploads to make Bazel faster
TypeScript
79
star
9

ruby-asana

Official Ruby client library for the Asana API v1
Ruby
76
star
10

bazeltsc

TypeScript compiler that knows how to run as a Bazel "persistent worker"
TypeScript
39
star
11

java-asana

Official Java client library for the Asana API v1
Java
35
star
12

create-app-attachment-github-action

TypeScript
33
star
13

devrel-examples

A place to share some examples from our Developer Relations team for commonly-asked-about workflows.
Python
27
star
14

comment-on-task-github-action

TypeScript
25
star
15

asana2sql

Utility for exporting Asana data to SQL databases
Python
23
star
16

api-explorer

React component to explore the Asana API
TypeScript
19
star
17

omniauth-asana

Official Asana strategy for OmniAuth
Ruby
16
star
18

SGTM

Python
14
star
19

asana-api-meta

Metadata for Asana API for generating client libraries and documenation
HTML
11
star
20

kraken-node-client

A nodejs client for the Kraken pubsub server
JavaScript
10
star
21

tsutil

TypeScript Utility Data Structures
TypeScript
9
star
22

node-asana-phrase

A random error phrase generator used to create memorable error codes, as used by Asana.
JavaScript
9
star
23

typescript-namespace-imports-vscode-plugin

A VSCode plugin that makes it easier to automatically include TypeScript namespace imports.
TypeScript
6
star
24

asana-shift

A small node script which uses the Asana API to shift all task start and due dates relative to a project's due date.
TypeScript
5
star
25

markdown-formatter

JavaScript
5
star
26

random-one-on-one

Python
5
star
27

app-components-example-app

app-components-example-app
JavaScript
4
star
28

ohmega

The Asana Ohmega process automation toolkit
Python
4
star
29

openapi

Python
4
star
30

sshca

Certificate authority for OpenSSH
Python
3
star
31

jira-server-plugin

Asana for Jira Server
3
star
32

node-asana-preview

A preview of Asana's new node client library
JavaScript
3
star
33

app-components-rule-action-example-app

JavaScript
3
star
34

python-asana-preview

A preview of Asana's new python client library
Python
3
star
35

node-sync-to-github

A node library that makes it easy to sync a directory of files to a GitHub repo using the GitHub API
JavaScript
3
star
36

deprovision_inactive_guests

A small script which uses the Asana API to remove external users (ie without a company email) from an organization if they haven't logged in for 30 days
JavaScript
2
star
37

archie

Python
2
star
38

formula-custom-fields

JavaScript
1
star
39

node-linux-fork

An implementation of fork() for Node.JS in Linux (requires a custom Node.JS build)
C++
1
star