MHPY-10 documentation

README.md

@@ -4,6 +4,10 @@
 
 The Mediahaven Python library provides a way to communicate with MediaHaven via the v2 REST API.
 
+## Documentation
+
+For more information about the internals of this library: see the automatically generated [documentation](/docs/README.md).
+
 ## Usage
 
 ```python

docs/README.md

@@ -0,0 +1,14 @@
+# Mediahaven-python Index
+
+> Auto-generated documentation index.
+
+A full list of `Mediahaven-python` project modules.
+
+- [MediaHaven](mediahaven/index.md#mediahaven)
+    - [Mediahaven](mediahaven/mediahaven.md#mediahaven)
+    - [Oauth2](mediahaven/oauth2.md#oauth2)
+    - [Resources](mediahaven/resources/index.md#resources)
+        - [BaseResource](mediahaven/resources/base_resource.md#baseresource)
+        - [FieldDefinitions](mediahaven/resources/field_definitions.md#fielddefinitions)
+        - [Organisations](mediahaven/resources/organisations.md#organisations)
+        - [Records](mediahaven/resources/records.md#records)

docs/mediahaven/index.md

@@ -0,0 +1,34 @@
+# MediaHaven
+
+[Mediahaven-python Index](../README.md#mediahaven-python-index) /
+MediaHaven
+
+> Auto-generated documentation for [mediahaven](../../mediahaven/__init__.py) module.
+
+- [MediaHaven](#mediahaven)
+  - [MediaHaven](#mediahaven-1)
+  - [Modules](#modules)
+
+## MediaHaven
+
+[Show source in __init__.py:12](../../mediahaven/__init__.py#L12)
+
+#### Signature
+
+```python
+class MediaHaven(MediaHavenClient):
+    def __init__(self, *args, **kwargs):
+        ...
+```
+
+#### See also
+
+- [MediaHavenClient](./mediahaven.md#mediahavenclient)
+
+
+
+## Modules
+
+- [Mediahaven](./mediahaven.md)
+- [Oauth2](./oauth2.md)
+- [Resources](resources/index.md)

docs/mediahaven/mediahaven.md

@@ -0,0 +1,57 @@
+# Mediahaven
+
+[Mediahaven-python Index](../README.md#mediahaven-python-index) /
+[MediaHaven](./index.md#mediahaven) /
+Mediahaven
+
+> Auto-generated documentation for [mediahaven.mediahaven](../../mediahaven/mediahaven.py) module.
+
+- [Mediahaven](#mediahaven)
+  - [AcceptFormat](#acceptformat)
+  - [MediaHavenClient](#mediahavenclient)
+  - [MediaHavenException](#mediahavenexception)
+
+## AcceptFormat
+
+[Show source in mediahaven.py:31](../../mediahaven/mediahaven.py#L31)
+
+#### Signature
+
+```python
+class AcceptFormat(Enum):
+    ...
+```
+
+
+
+## MediaHavenClient
+
+[Show source in mediahaven.py:42](../../mediahaven/mediahaven.py#L42)
+
+The MediaHaven client class to communicate with MediaHaven.
+
+#### Signature
+
+```python
+class MediaHavenClient:
+    def __init__(self, mh_base_url: str, grant: OAuth2Grant):
+        ...
+```
+
+#### See also
+
+- [OAuth2Grant](./oauth2.md#oauth2grant)
+
+
+
+## MediaHavenException
+
+[Show source in mediahaven.py:25](../../mediahaven/mediahaven.py#L25)
+
+#### Signature
+
+```python
+class MediaHavenException(Exception):
+    def __init__(self, message: str, status_code: int = None):
+        ...
+```

docs/mediahaven/oauth2.md

@@ -0,0 +1,157 @@
+# Oauth2
+
+[Mediahaven-python Index](../README.md#mediahaven-python-index) /
+[MediaHaven](./index.md#mediahaven) /
+Oauth2
+
+> Auto-generated documentation for [mediahaven.oauth2](../../mediahaven/oauth2.py) module.
+
+- [Oauth2](#oauth2)
+  - [NoTokenError](#notokenerror)
+  - [OAuth2Grant](#oauth2grant)
+    - [OAuth2Grant().refresh_token](#oauth2grant()refresh_token)
+    - [OAuth2Grant().request_token](#oauth2grant()request_token)
+  - [ROPCGrant](#ropcgrant)
+    - [ROPCGrant().request_token](#ropcgrant()request_token)
+  - [RefreshTokenError](#refreshtokenerror)
+  - [RequestTokenError](#requesttokenerror)
+
+## NoTokenError
+
+[Show source in oauth2.py:38](../../mediahaven/oauth2.py#L38)
+
+Raised when a token has not been requested yet.
+
+#### Signature
+
+```python
+class NoTokenError(Exception):
+    def __init__(self):
+        ...
+```
+
+
+
+## OAuth2Grant
+
+[Show source in oauth2.py:45](../../mediahaven/oauth2.py#L45)
+
+Abstract class representing an OAuth2 grant used in MediaHaven.
+
+#### Signature
+
+```python
+class OAuth2Grant(ABC):
+    def __init__(self, mh_base_url: str, client_id: str, client_secret: str):
+        ...
+```
+
+### OAuth2Grant().refresh_token
+
+[Show source in oauth2.py:67](../../mediahaven/oauth2.py#L67)
+
+Refresh the OAuth2 token with the saved refresh token.
+
+Issues a new access token but also a new refresh token.
+
+#### Signature
+
+```python
+def refresh_token(self):
+    ...
+```
+
+### OAuth2Grant().request_token
+
+[Show source in oauth2.py:63](../../mediahaven/oauth2.py#L63)
+
+#### Signature
+
+```python
+@abstractmethod
+def request_token(self):
+    ...
+```
+
+
+
+## ROPCGrant
+
+[Show source in oauth2.py:96](../../mediahaven/oauth2.py#L96)
+
+Represents a "Resource Owner Password Credential" grant.
+
+#### Signature
+
+```python
+class ROPCGrant(OAuth2Grant):
+    def __init__(self, mh_base_url: str, client_id: str, client_secret: str):
+        ...
+```
+
+#### See also
+
+- [OAuth2Grant](#oauth2grant)
+
+### ROPCGrant().request_token
+
+[Show source in oauth2.py:104](../../mediahaven/oauth2.py#L104)
+
+Request an OAuth2 token.
+
+The resource owner grants the client the authorization to execute the
+requests on its behalf. Given the credentials of the resource owner, an auth
+token is issued by the authorization server. This token will be saved in memory
+and used by the session in order to execute authorized requests.
+
+#### Arguments
+
+- `username` - The username of the resource owner.
+- `password` - The password of the resource owner.
+
+#### Raises
+
+- `RequestTokenException` - When an error occurred when requesting the token.
+
+#### Signature
+
+```python
+def request_token(self, username: str, password: str):
+    ...
+```
+
+
+
+## RefreshTokenError
+
+[Show source in oauth2.py:28](../../mediahaven/oauth2.py#L28)
+
+Raised when an error occurred during token request.
+
+Abstracts the underlying OAuthlib2 errors.
+
+#### Signature
+
+```python
+class RefreshTokenError(Exception):
+    def __init__(self):
+        ...
+```
+
+
+
+## RequestTokenError
+
+[Show source in oauth2.py:18](../../mediahaven/oauth2.py#L18)
+
+Raised when an error occurred during token request.
+
+Abstracts the underlying OAuthlib2 errors.
+
+#### Signature
+
+```python
+class RequestTokenError(Exception):
+    def __init__(self):
+        ...
+```