Skip to content

API Reference

doky.AuthSession

Creates an object to manage the authentication session.

Parameters:

Name Type Description Default
session_id str

Your session ID from labs.play-with-docker.com

 required
Source code in doky/auth_session.py 
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
class AuthSession:
    """
    Creates an object to manage the authentication session.

    Parameters:
        session_id:
            Your session ID from labs.play-with-docker.com
    """
    def __init__(self, session_id: str) -> None:
        # Checking if the `session_id` parameter is a string type.
        if not isinstance(session_id, str):
            raise errors.type_error(('session_id', session_id), str)

        # Creating a http client session.
        self._http_client = create_http_client()

        # Using the same cookie from navigator.
        self._http_client.cookies['id'] = session_id

    @staticmethod
    def get_providers() -> List[str]:
        """
        Static method that requests for a list of available providers.

        Returns:
            List of available providers.

        Return Example:
            ```python3
            ['docker']
            ```

        Raises:
            httpx.HTTPStatusError:
                Bad response HTTP status code.
        """
        # Creating a http client session and requesting for a providers list.
        request = create_http_client().get('/oauth/providers')

        try:
            # Raise if response status code is bad.
            request.raise_for_status()
        except httpx.HTTPStatusError as exception:
            # Adding an exception message note.
            exception.add_note('\n' + errors.OPEN_AN_ISSUE)
            # Raising the same exception again.
            raise

        # Returning providers list.
        return request.json()

    @staticmethod
    def request_oauth_url(provider: str = 'docker') -> str:
        """
        Static method that requests an OAuth URL to a provider.

        Parameters:
            provider:
                The OAuth available provider.

        Returns:
            The OAuth URL for authentication.

        Return Example:
            ```
            https://login.docker.com/authorize/?client_id=XXXXXX&nonce=XXXXXX&redirect_uri=XXXXXX&response_type=code&scope=XXXXXX&state=XXXXXX
            ```

        Raises:
            RuntimeError: Some unexpected error.
        """
        # Checking if the `provider` parameter is a string type.
        if not isinstance(provider, str):
            raise errors.type_error(('provider', provider), str)

        # Creating a http client session and requesting OAuth URL from the
        # provider specified.
        request = create_http_client().get(
            url='/oauth/providers/' + urlencode(provider) + '/login',
            follow_redirects=False
        )

        # Raise an exception if the response status code is not 302 FOUND.
        if request.status_code != HTTPStatus.FOUND:
            raise RuntimeError(
                'The authentication provider endpoint is not redirecting, '
                'perhaps it is broken.\n\n' + errors.OPEN_AN_ISSUE
            )

        # Getting OAuth URL from redirect header Location.
        oauth_url = request.headers.get('Location')

        # Raise an exception if the redirect header location doesn't exists.
        if not oauth_url:
            raise RuntimeError(
                'It appears that the server is not returning the '
                'authentication URL.\n\n' + errors.OPEN_AN_ISSUE
            )

        # Returning the OAuth URL.
        return oauth_url

    def get_me(self) -> dict:
        """
        Bound method that requests for current user session informations.

        Returns:
            Current user session informations.

        Return Example:
            ```python3
            {
                'id': 'XXXXXX',
                'name': 'd3cryptofc',
                'provider_user_id': '1000XXX',
                'avatar': 'https://avatars.io/twitter/d3cryptofc',
                'provider': 'docker',
                'email': 'd3cryptofc@gmail.com',
                'banned': False
            }
            ```

        Raises:
            httpx.HTTPStatusError:
                Bad response HTTP status code.
        """
        # Requesting for current user session informations.
        request = self._http_client.get('/users/me')

        try:
            # Raise if response status code is bad.
            request.raise_for_status()
        except httpx.HTTPStatusError as exception:
            # Adding an exception message note.
            exception.add_note('\n' + errors.OPEN_AN_ISSUE)
            # Raising the same exception again.
            raise

        # Returning the current user session informations.
        return request.json()

get_me()

Bound method that requests for current user session informations.

Returns:

Type Description
dict

Current user session informations.
Return Example 
{
    'id': 'XXXXXX',
    'name': 'd3cryptofc',
    'provider_user_id': '1000XXX',
    'avatar': 'https://avatars.io/twitter/d3cryptofc',
    'provider': 'docker',
    'email': 'd3cryptofc@gmail.com',
    'banned': False
}

Raises:

Type Description
HTTPStatusError

Bad response HTTP status code.
Source code in doky/auth_session.py 
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
def get_me(self) -> dict:
    """
    Bound method that requests for current user session informations.

    Returns:
        Current user session informations.

    Return Example:
        ```python3
        {
            'id': 'XXXXXX',
            'name': 'd3cryptofc',
            'provider_user_id': '1000XXX',
            'avatar': 'https://avatars.io/twitter/d3cryptofc',
            'provider': 'docker',
            'email': 'd3cryptofc@gmail.com',
            'banned': False
        }
        ```

    Raises:
        httpx.HTTPStatusError:
            Bad response HTTP status code.
    """
    # Requesting for current user session informations.
    request = self._http_client.get('/users/me')

    try:
        # Raise if response status code is bad.
        request.raise_for_status()
    except httpx.HTTPStatusError as exception:
        # Adding an exception message note.
        exception.add_note('\n' + errors.OPEN_AN_ISSUE)
        # Raising the same exception again.
        raise

    # Returning the current user session informations.
    return request.json()

get_providers() staticmethod

Static method that requests for a list of available providers.

Returns:

Type Description
List[str]

List of available providers.
Return Example 
['docker']

Raises:

Type Description
HTTPStatusError

Bad response HTTP status code.
Source code in doky/auth_session.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
@staticmethod
def get_providers() -> List[str]:
    """
    Static method that requests for a list of available providers.

    Returns:
        List of available providers.

    Return Example:
        ```python3
        ['docker']
        ```

    Raises:
        httpx.HTTPStatusError:
            Bad response HTTP status code.
    """
    # Creating a http client session and requesting for a providers list.
    request = create_http_client().get('/oauth/providers')

    try:
        # Raise if response status code is bad.
        request.raise_for_status()
    except httpx.HTTPStatusError as exception:
        # Adding an exception message note.
        exception.add_note('\n' + errors.OPEN_AN_ISSUE)
        # Raising the same exception again.
        raise

    # Returning providers list.
    return request.json()

request_oauth_url(provider='docker') staticmethod

Static method that requests an OAuth URL to a provider.

Parameters:

Name Type Description Default
provider str

The OAuth available provider.

 'docker'

Returns:

Type Description
str

The OAuth URL for authentication.
Return Example 
https://login.docker.com/authorize/?client_id=XXXXXX&nonce=XXXXXX&redirect_uri=XXXXXX&response_type=code&scope=XXXXXX&state=XXXXXX

Raises:

Type Description
RuntimeError

Some unexpected error.
Source code in doky/auth_session.py 
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
@staticmethod
def request_oauth_url(provider: str = 'docker') -> str:
    """
    Static method that requests an OAuth URL to a provider.

    Parameters:
        provider:
            The OAuth available provider.

    Returns:
        The OAuth URL for authentication.

    Return Example:
        ```
        https://login.docker.com/authorize/?client_id=XXXXXX&nonce=XXXXXX&redirect_uri=XXXXXX&response_type=code&scope=XXXXXX&state=XXXXXX
        ```

    Raises:
        RuntimeError: Some unexpected error.
    """
    # Checking if the `provider` parameter is a string type.
    if not isinstance(provider, str):
        raise errors.type_error(('provider', provider), str)

    # Creating a http client session and requesting OAuth URL from the
    # provider specified.
    request = create_http_client().get(
        url='/oauth/providers/' + urlencode(provider) + '/login',
        follow_redirects=False
    )

    # Raise an exception if the response status code is not 302 FOUND.
    if request.status_code != HTTPStatus.FOUND:
        raise RuntimeError(
            'The authentication provider endpoint is not redirecting, '
            'perhaps it is broken.\n\n' + errors.OPEN_AN_ISSUE
        )

    # Getting OAuth URL from redirect header Location.
    oauth_url = request.headers.get('Location')

    # Raise an exception if the redirect header location doesn't exists.
    if not oauth_url:
        raise RuntimeError(
            'It appears that the server is not returning the '
            'authentication URL.\n\n' + errors.OPEN_AN_ISSUE
        )

    # Returning the OAuth URL.
    return oauth_url