pyinaturalist 1.0.0.dev0__tar.gz → 1.0.0.dev2__tar.gz

{pyinaturalist-1.0.0.dev0 → pyinaturalist-1.0.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pyinaturalist
-Version: 1.0.0.dev0
+Version: 1.0.0.dev2
 Summary: iNaturalist API client for python
 Project-URL: homepage, https://github.com/pyinat/pyinaturalist
 Project-URL: repository, https://github.com/pyinat/pyinaturalist

{pyinaturalist-1.0.0.dev0 → pyinaturalist-1.0.0.dev2}/pyinaturalist/__init__.py

@@ -1,13 +1,10 @@
 # ruff: noqa: F401, F403
 # isort: skip_file
-from pyinaturalist.auth import get_access_token
-from pyinaturalist.client import iNatClient
+from pyinaturalist.client import *
 from pyinaturalist.constants import *
 from pyinaturalist.formatters import enable_logging, format_table, pprint, pprint_tree
 from pyinaturalist.models import *
-from pyinaturalist.paginator import Paginator, IDPaginator, WrapperPaginator
 from pyinaturalist.request_params import get_interval_ranges
-from pyinaturalist.session import ClientSession, FileLockSQLiteBucket, clear_cache
 from pyinaturalist.v0 import *
 from pyinaturalist.v2 import *
 from pyinaturalist.v1 import *

pyinaturalist-1.0.0.dev2/pyinaturalist/client/__init__.py

@@ -0,0 +1,31 @@
+# ruff: noqa: F401, F403, F405
+# isort: skip_file
+from pyinaturalist.client.paginator import *
+from pyinaturalist.client.session import *
+from pyinaturalist.client.oauth import *
+from pyinaturalist.client.oauth_callback import *
+from pyinaturalist.client.client import iNatClient
+
+__all__ = [
+    'AutocompletePaginator',
+    'ClientSession',
+    'FileLockSQLiteBucket',
+    'IDPaginator',
+    'IDRangePaginator',
+    'JsonPaginator',
+    'Paginator',
+    'WrapperPaginator',
+    'build_authorize_url',
+    'clear_cache',
+    'delete',
+    'get',
+    'get_access_token',
+    'get_access_token_via_auth_code',
+    'get_auth_code_via_server',
+    'get_local_session',
+    'iNatClient',
+    'paginate_all',
+    'post',
+    'put',
+    'set_keyring_credentials',
+]

{pyinaturalist-1.0.0.dev0/pyinaturalist → pyinaturalist-1.0.0.dev2/pyinaturalist/client}/client.py

@@ -3,30 +3,73 @@
 # TODO: Use a custom template or directive to generate summary of all controller methods
 from asyncio import AbstractEventLoop
 from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
 from inspect import ismethod
 from logging import getLogger
-from typing import Any
+from typing import Any, Literal
 
-from pyinaturalist.auth import get_access_token
+from requests import HTTPError
+
+from pyinaturalist.client.oauth import (
+    _decode_jwt_exp,
+    get_access_token,
+    get_access_token_via_auth_code,
+)
+from pyinaturalist.client.paginator import Paginator
+from pyinaturalist.client.session import ClientSession
 from pyinaturalist.constants import RequestParams
 from pyinaturalist.controllers import (
     AnnotationController,
     IdentificationController,
     ObservationController,
+    ObservationFieldController,
     PlaceController,
     ProjectController,
     SearchController,
     TaxonController,
     UserController,
 )
+from pyinaturalist.exceptions import AuthenticationError
 from pyinaturalist.models import T
-from pyinaturalist.paginator import Paginator
 from pyinaturalist.request_params import get_valid_kwargs, strip_empty_values
-from pyinaturalist.session import ClientSession
+
+JWT_EXPIRY_BUFFER = timedelta(seconds=60)
 
 logger = getLogger(__name__)
 
 
+@dataclass
+class _TokenInfo:
+    """Internal record of a fetched access token and its metadata."""
+
+    token: str
+    obtained_at: datetime  # UTC datetime when the token was fetched
+    flow: Literal['password', 'authorization_code']
+    expires_at: datetime | None  # decoded from JWT exp claim; None for non-JWT tokens
+
+
+AUTH_CODE_CRED_KEYS = frozenset(
+    {
+        'app_id',
+        'app_secret',
+        'use_pkce',
+        'use_oob',
+        'refresh',
+        'port',
+        'timeout',
+        'open_url',
+        'get_code',
+        # Note: 'auth_flow' is intentionally excluded — it's a client-level key, not a
+        # parameter accepted by get_access_token_via_auth_code().
+    }
+)
+
+PASSWORD_FLOW_CRED_KEYS = frozenset({'username', 'password', 'app_id', 'app_secret', 'refresh'})
+
+SUPPORTED_AUTH_FLOWS = frozenset({'password', 'authorization_code'})
+
+
 # 'iNatClient' is nonstandard casing, but 'InatClient' just looks wrong. Deal with it, pep8.
 class iNatClient:
     """API client class that provides an object-oriented interface to the iNaturalist API.
@@ -41,6 +84,7 @@ class iNatClient:
     * :fa:`tag` :py:class:`annotations <.AnnotationController>`
     * :fa:`fingerprint` :py:class:`identifications <.IdentificationController>`
     * :fa:`binoculars` :py:class:`observations <.ObservationController>`
+    * :fa:`tag` :py:class:`observation_fields <.ObservationFieldController>`
     * :fa:`location-dot` :py:class:`places <.PlaceController>`
     * :fa:`users` :py:class:`projects <.ProjectController>`
     * :fa:`search` :py:class:`search <.SearchController>`
@@ -48,8 +92,10 @@ class iNatClient:
     * :fa:`user` :py:class:`users <.UserController>`
 
     Args:
-        creds: Optional arguments for :py:func:`.get_access_token`, used to get and refresh access
-            tokens as needed. Using a keyring instead is recommended, though.
+        creds: Optional arguments for :py:func:`.get_access_token` or
+            :py:func:`.get_access_token_via_auth_code`, used to get and refresh access
+            tokens as needed. Use ``auth_flow='authorization_code'`` to select authorization code
+            flow; otherwise password flow is used.
         default_params: Default request parameters to pass to any applicable API requests
         dry_run: Just log all requests instead of sending real requests
         loop: An event loop to run any executors used for async iteration
@@ -59,7 +105,7 @@ class iNatClient:
 
     def __init__(
         self,
-        creds: dict[str, str] | None = None,
+        creds: dict[str, Any] | None = None,
         default_params: dict[str, Any] | None = None,
         dry_run: bool = False,
         loop: AbstractEventLoop | None = None,
@@ -67,13 +113,17 @@ class iNatClient:
         **kwargs,
     ):
         self.creds = creds or {}
+        auth_flow = self.creds.get('auth_flow')
+        if auth_flow is not None and auth_flow not in SUPPORTED_AUTH_FLOWS:
+            raise AuthenticationError(
+                f'Unsupported auth_flow {auth_flow!r}. '
+                f'Accepted values: {sorted(SUPPORTED_AUTH_FLOWS)}'
+            )
         self.default_params = default_params or {}
         self.dry_run = dry_run
         self.loop = loop
         self.session = session or ClientSession(**kwargs)
-
-        self._access_token = None
-        self._token_expires = None
+        self._token_info: _TokenInfo | None = None
 
         # Controllers
         self.annotations = AnnotationController(
@@ -85,6 +135,9 @@ class iNatClient:
         self.observations = ObservationController(
             self
         )  #: Interface for :py:class:`observation requests <.ObservationController>`
+        self.observation_fields = ObservationFieldController(
+            self
+        )  #: Interface for :py:class:`observation field requests <.ObservationFieldController>`
         self.places = PlaceController(
             self
         )  #: Interface for :py:class:`place requests <.PlaceController>`
@@ -112,8 +165,9 @@ class iNatClient:
 
         # Add access token if needed
         if auth:
-            access_token = kwargs.pop('access_token', None) or get_access_token(**self.creds)  # type: ignore
-            client_kwargs['access_token'] = access_token
+            access_token = self._resolve_access_token(kwargs)
+            if access_token:
+                client_kwargs['access_token'] = access_token
 
         # Add default request parameters if applicable
         client_kwargs.update(get_valid_kwargs(request_function, self.default_params))
@@ -126,6 +180,48 @@ class iNatClient:
 
         return kwargs
 
+    def _resolve_access_token(self, kwargs: RequestParams) -> str | None:
+        """Resolve an access token from request args, client cache, or credentials."""
+        access_token = kwargs.pop('access_token', None)
+        if access_token:
+            return access_token
+        if self._token_info:
+            still_valid = self._token_info.expires_at is None or self._token_info.expires_at > (
+                datetime.now(tz=timezone.utc) + JWT_EXPIRY_BUFFER
+            )
+            if still_valid:
+                return self._token_info.token
+            # Token is expired or about to expire — fall through to re-fetch
+            self._token_info = None
+        self._token_info = self._fetch_access_token_from_creds()
+        return self._token_info.token
+
+    def _fetch_access_token_from_creds(self, force_refresh: bool = False) -> _TokenInfo:
+        """Get a new access token from configured credentials and wrap it in _TokenInfo."""
+        flow = self.creds.get('auth_flow', 'password')
+        if flow == 'authorization_code':
+            auth_code_creds = self._filter_creds(AUTH_CODE_CRED_KEYS, self.creds)
+            if force_refresh:
+                auth_code_creds['refresh'] = True
+            token = get_access_token_via_auth_code(**auth_code_creds)
+        else:
+            token_creds = self._filter_creds(PASSWORD_FLOW_CRED_KEYS, self.creds)
+            if force_refresh:
+                token_creds['refresh'] = True
+            token = get_access_token(**token_creds)
+
+        return _TokenInfo(
+            token=token,
+            obtained_at=datetime.now(tz=timezone.utc),
+            flow=flow,
+            expires_at=_decode_jwt_exp(token),
+        )
+
+    @staticmethod
+    def _filter_creds(valid_keys: frozenset, creds: dict[str, Any]) -> dict[str, Any]:
+        """Keep only credentials accepted by the selected auth flow."""
+        return {k: v for k, v in creds.items() if k in valid_keys}
+
     def paginate(
         self,
         request_function: Callable,
@@ -157,5 +253,19 @@ class iNatClient:
         Returns:
             Results of ``request_function()``
         """
+        explicit_access_token = kwargs.get('access_token') is not None
         kwargs = self.add_defaults(request_function, kwargs, auth)
-        return request_function(*args, **kwargs)
+        try:
+            return request_function(*args, **kwargs)
+        except HTTPError as e:
+            if not auth or explicit_access_token or not self._is_unauthorized_error(e):
+                raise
+            self._token_info = self._fetch_access_token_from_creds(force_refresh=True)
+            kwargs = kwargs.copy()
+            kwargs['access_token'] = self._token_info.token
+            return request_function(*args, **kwargs)
+
+    @staticmethod
+    def _is_unauthorized_error(error: HTTPError) -> bool:
+        response = getattr(error, 'response', None)
+        return bool(response is not None and response.status_code == 401)

pyinaturalist-1.0.0.dev2/pyinaturalist/client/oauth.py

@@ -0,0 +1,337 @@
+import base64
+import binascii
+import json
+import secrets
+from collections.abc import Callable
+from datetime import datetime, timezone
+from logging import getLogger
+from os import getenv
+
+from keyring import get_password, set_password
+from keyring.errors import KeyringError
+from requests import HTTPError, Response
+
+from pyinaturalist.client.oauth_callback import (
+    _build_token_payload,
+    _generate_pkce_pair,
+    _obtain_auth_code,
+    _resolve_auth_code_creds,
+    build_authorize_url,
+)
+from pyinaturalist.client.session import ClientSession, get_local_session
+from pyinaturalist.constants import API_V0, API_V1, KEYRING_KEY
+from pyinaturalist.exceptions import AuthenticationError
+
+_logger = getLogger(__name__)
+
+
+def _decode_jwt_exp(token: str) -> datetime | None:
+    """Decode the exp claim from a JWT without verifying the signature.
+
+    Returns the expiry as a UTC datetime, or None if the token is not a
+    decodable JWT or has no exp claim.
+    """
+    try:
+        parts = token.split('.')
+        if len(parts) != 3:
+            return None
+        # Add padding required by base64
+        payload_b64 = parts[1] + '=' * (-len(parts[1]) % 4)
+        payload = json.loads(base64.urlsafe_b64decode(payload_b64))
+        exp = payload.get('exp')
+        return datetime.fromtimestamp(exp, tz=timezone.utc) if exp else None
+    except (
+        ValueError,
+        KeyError,
+        AttributeError,
+        OverflowError,
+        OSError,
+        TypeError,
+        binascii.Error,
+    ):
+        return None
+
+
+def get_access_token(
+    username: str | None = None,
+    password: str | None = None,
+    app_id: str | None = None,
+    app_secret: str | None = None,
+    jwt: bool = True,
+    refresh: bool = False,
+) -> str:
+    """Get an access token using the user's iNaturalist username and password, using the
+    Resource Owner Password Credentials Flow. Requires registering an iNaturalist app.
+
+    .. rubric:: Notes
+
+    * API reference: https://www.inaturalist.org/pages/api+reference#auth
+    * See :ref:`auth` for additional options for storing credentials.
+    * This can be used to get either a JWT or OAuth token. These can be used interchangeably for
+      many endpoints. JWT is preferred for newer endpoints.
+
+    Examples:
+
+        With direct keyword arguments:
+
+        >>> from pyinaturalist import get_access_token
+        >>> access_token = get_access_token(
+        >>>     username='my_inaturalist_username',
+        >>>     password='my_inaturalist_password',
+        >>>     app_id='33f27dc63bdf27f4ca6cd95dd9dcd5df',
+        >>>     app_secret='bbce628be722bfe2abd5fc566ba83de4',
+        >>> )
+
+        With environment variables or keyring configured:
+
+        >>> access_token = get_access_token()
+
+        If you would like to run custom requests for endpoints not yet implemented in pyinaturalist,
+        you can authenticate these requests by putting the token in your HTTP headers as follows:
+
+        >>> import requests
+        >>> requests.get(
+        >>>     'https://www.inaturalist.org/observations/1234',
+        >>>      headers={'Authorization': f'Bearer {access_token}'},
+        >>> )
+
+    Args:
+        username: iNaturalist username (same as the one you use to login on inaturalist.org)
+        password: iNaturalist password (same as the one you use to login on inaturalist.org)
+        app_id: OAuth2 application ID
+        app_secret: OAuth2 application secret
+        jwt: Return a JSON Web Token; otherwise return an OAuth2 access token.
+        refresh: Do not use any cached tokens, even if they are not expired
+
+    Raises:
+        :py:exc:`requests.HTTPError`: (401) if credentials are invalid
+        :py:exc:`.AuthenticationError`: if required credentials are missing
+    """
+    session, cached = _get_cached_jwt(refresh)
+    if cached and jwt:
+        return cached
+
+    # Otherwise check for credentials in either args or environment variables
+    payload = {
+        'username': username or getenv('INAT_USERNAME'),
+        'password': password or getenv('INAT_PASSWORD'),
+        'client_id': app_id or getenv('INAT_APP_ID'),
+        'client_secret': app_secret or getenv('INAT_APP_SECRET'),
+        'grant_type': 'password',
+    }
+
+    # If any fields were missing, then check the keyring
+    if not all(payload.values()):
+        payload |= {k: v for k, v in get_keyring_credentials().items() if not payload.get(k)}
+        if all(payload.values()):
+            _logger.info('Retrieved credentials from keyring')
+        else:
+            raise AuthenticationError('Not all authentication parameters were provided')
+
+    # Get OAuth access token
+    response = session.post(f'{API_V0}/oauth/token', json=payload)
+    access_token = response.json()['access_token']
+
+    # If specified, use OAuth token to get (and cache) a JWT
+    if jwt:
+        response = _get_jwt(session, access_token, refresh=refresh)
+        response.raise_for_status()
+        access_token = response.json()['api_token']
+    return access_token
+
+
+def get_access_token_via_auth_code(
+    app_id: str | None = None,
+    app_secret: str | None = None,
+    use_pkce: bool = True,
+    use_oob: bool = False,
+    jwt: bool = True,
+    refresh: bool = False,
+    port: int = 8080,
+    timeout: int = 120,
+    open_url: Callable[[str], None] | None = None,
+    get_code: Callable[[str], str] | None = None,
+) -> str:
+    """Get an access token using the OAuth2 Authorization Code flow, optionally with PKCE.
+
+    This is the recommended approach for CLI and desktop applications because users do not
+    need to provide their iNaturalist password to third-party code. Instead, the user
+    authenticates directly on inaturalist.org in their browser.
+
+    .. rubric:: Notes
+
+    * Requires registering an iNaturalist application at
+      https://www.inaturalist.org/oauth/applications
+    * When using PKCE (the default), no client secret is needed.
+    * When using the local callback server, register your redirect URI as
+      ``http://127.0.0.1:<port>`` (e.g., ``http://127.0.0.1:8080``).
+    * When using OOB mode, register your redirect URI as
+      ``urn:ietf:wg:oauth:2.0:oob``.
+
+    Examples:
+
+        With PKCE (recommended, no client secret needed):
+
+        >>> from pyinaturalist import get_access_token_via_auth_code
+        >>> access_token = get_access_token_via_auth_code(
+        ...     app_id='33f27dc63bdf27f4ca6cd95dd9dcd5df',
+        ... )
+
+        Without PKCE (requires client secret):
+
+        >>> access_token = get_access_token_via_auth_code(
+        ...     app_id='33f27dc63bdf27f4ca6cd95dd9dcd5df',
+        ...     app_secret='bbce628be722bfe2abd5fc566ba83de4',
+        ...     use_pkce=False,
+        ... )
+
+        For headless/remote environments (OOB mode):
+
+        >>> access_token = get_access_token_via_auth_code(
+        ...     app_id='33f27dc63bdf27f4ca6cd95dd9dcd5df',
+        ...     use_oob=True,
+        ... )
+
+    Args:
+        app_id: OAuth2 application ID. Falls back to ``INAT_APP_ID`` env var or keyring.
+        app_secret: OAuth2 application secret. Required when ``use_pkce=False``.
+        use_pkce: Use PKCE (Proof Key for Code Exchange) instead of a client secret.
+        use_oob: Use out-of-band mode: the user manually copies the authorization code
+            instead of using a local callback server. Useful for headless environments.
+        jwt: Return a JSON Web Token; otherwise return an OAuth2 access token.
+        refresh: Do not use any cached tokens, even if they are not expired.
+        port: Port for the local callback server. Must match the redirect URI registered
+            with your iNaturalist application.
+        timeout: Seconds to wait for the user to complete authorization in the browser.
+        open_url: Optional callback to open the authorization URL. Defaults to
+            ``webbrowser.open``. Useful for testing or custom browser handling.
+        get_code: Optional callback for OOB mode that receives the authorization URL and
+            returns the authorization code entered by the user. Defaults to ``input()``.
+
+    Raises:
+        :py:exc:`.AuthenticationError`: if credentials are missing, the user does not
+            authorize in time, or the token exchange fails.
+    """
+    session, cached = _get_cached_jwt(refresh)
+    if cached and jwt:
+        return cached
+
+    app_id, app_secret = _resolve_auth_code_creds(app_id, app_secret, use_pkce)
+
+    # Generate PKCE pair if needed
+    code_verifier: str | None = None
+    code_challenge: str | None = None
+    if use_pkce:
+        code_verifier, code_challenge = _generate_pkce_pair()
+
+    # Build authorization URL and get the authorization code
+    redirect_uri = 'urn:ietf:wg:oauth:2.0:oob' if use_oob else f'http://127.0.0.1:{port}'
+    state = secrets.token_urlsafe(32) if not use_oob else None
+    authorize_url = build_authorize_url(app_id, redirect_uri, code_challenge, state)
+    auth_code = _obtain_auth_code(
+        authorize_url,
+        use_oob=use_oob,
+        port=port,
+        timeout=timeout,
+        state=state,
+        open_url=open_url,
+        get_code=get_code,
+    )
+
+    # Exchange authorization code for access token
+    payload = _build_token_payload(
+        app_id, auth_code, redirect_uri, code_verifier, app_secret, use_pkce
+    )
+    response = session.post(f'{API_V0}/oauth/token', json=payload)
+    access_token = response.json()['access_token']
+
+    # If specified, use OAuth token to get (and cache) a JWT
+    if jwt:
+        response = _get_jwt(session, access_token, refresh=refresh)
+        response.raise_for_status()
+        access_token = response.json()['api_token']
+    return access_token
+
+
+def _get_cached_jwt(refresh: bool) -> tuple[ClientSession, str | None]:
+    """Return (session, token) if a valid cached JWT exists"""
+    session = get_local_session()
+    response = _get_jwt(session, only_if_cached=True)
+    if response.ok and not refresh:
+        _logger.info('Using cached access token')
+        return session, response.json()['api_token']
+    return session, None
+
+
+def validate_token(access_token: str) -> bool:
+    """Determine if an access token is valid.
+
+    Returns ``False`` when the server confirms the token is invalid (401);
+    other failures are not re-raised.
+
+    Raises:
+        :py:exc:`requests.HTTPError`: for any non-401 error response
+    """
+    session = get_local_session()
+    try:
+        session.request('GET', f'{API_V1}/users/me', access_token=access_token)
+        return True
+    except HTTPError as e:
+        if e.response is not None and e.response.status_code == 401:
+            return False
+        raise
+
+
+def get_keyring_credentials() -> dict[str, str | None]:
+    """Attempt to get iNaturalist credentials from the system keyring
+
+    Returns:
+        OAuth-compatible credentials dict
+    """
+    try:
+        return {
+            'username': get_password(KEYRING_KEY, 'username'),
+            'password': get_password(KEYRING_KEY, 'password'),
+            'client_id': get_password(KEYRING_KEY, 'app_id'),
+            'client_secret': get_password(KEYRING_KEY, 'app_secret'),
+        }
+    except KeyringError as e:
+        _logger.warning(e)
+        return {}
+
+
+def set_keyring_credentials(
+    username: str,
+    password: str,
+    app_id: str,
+    app_secret: str,
+):
+    """
+    Store iNaturalist credentials in the system keyring for future use.
+
+    Args:
+        username: iNaturalist username
+        password: iNaturalist password
+        app_id: iNaturalist application ID
+        app_secret: iNaturalist application secret
+    """
+    set_password(KEYRING_KEY, 'username', username)
+    set_password(KEYRING_KEY, 'password', password)
+    set_password(KEYRING_KEY, 'app_id', app_id)
+    set_password(KEYRING_KEY, 'app_secret', app_secret)
+
+
+def _get_jwt(
+    session: ClientSession,
+    access_token: str | None = None,
+    only_if_cached: bool = False,
+    refresh: bool = False,
+) -> Response:
+    headers = {'Authorization': f'Bearer {access_token}'} if access_token else {}
+    return session.get(
+        f'{API_V0}/users/api_token',
+        headers=headers,
+        only_if_cached=only_if_cached,  # If True, will return a 504 if not cached
+        force_refresh=refresh,
+        raise_for_status=False,  # type: ignore
+    )