######################
Personal Access Tokens
######################

References
----------

* v4 API:

  + :class:`gitlab.v4.objects.PersonalAccessToken`
  + :class:`gitlab.v4.objects.PersonalAcessTokenManager`
  + :attr:`gitlab.Gitlab.personal_access_tokens`
  + :class:`gitlab.v4.objects.UserPersonalAccessToken`
  + :class:`gitlab.v4.objects.UserPersonalAcessTokenManager`
  + :attr:`gitlab.Gitlab.User.personal_access_tokens`

* GitLab API:

  + https://docs.gitlab.com/ee/api/personal_access_tokens.html
  + https://docs.gitlab.com/ee/api/users.html#create-a-personal-access-token

Examples
--------

List personal access tokens::

    access_tokens = gl.personal_access_tokens.list()
    print(access_tokens[0].name)

List personal access tokens from other user_id (admin only)::

    access_tokens = gl.personal_access_tokens.list(user_id=25)

Revoke a personal access token fetched via list::

    access_token = access_tokens[0]
    access_token.delete()

Revoke a personal access token by id::

    gl.personal_access_tokens.delete(123)

Create a personal access token for a user (admin only)::

    user = gl.users.get(25, lazy=True)
    access_token = user.personal_access_tokens.create({"name": "test", "scopes": "api"})

.. note:: As you can see above, you can only create personal access tokens
    via the Users API, but you cannot revoke these objects directly.
    This is because the create API uses a different endpoint than the list and revoke APIs.
    You need to fetch the token via the list API first to revoke it.

    As of 14.2, GitLab does not provide a GET API for single personal access tokens.
    You must use the list method to retrieve single tokens.