Merge pull request #704 from pyinat/refactor

Reorganize client-related modules into `client` subpackage

Author: JWCook

HISTORY.md

@@ -124,6 +124,7 @@ In addition, checking attributes on nested objects will not raise `AttributeErro
   * Deprecate `FileLockSQLiteBucket` in favor of `use_file_lock` (but still available for backwards-compatibility)
 * Drop support for python 3.8 and 3.9 (removed upstream)
 * Remove `pyinaturalist.rest_api` and `pyinaturalist.node_api` modules (deprecated in 0.14)
+* Remove `get_observation` (deprecated in 0.18 and replaced by `get_observations` and `get_observations_by_id`)
 
 ## 0.21.1 (2026-02-13)
 * Update `v2.create_observation()` and `update_observation()` to accept multiple observation field values, consistent with v0 and v1 APIs.

docs/reference.md

@@ -32,11 +32,8 @@ pyinaturalist.models
 :glob: true
 :maxdepth: 1
 
-modules/pyinaturalist.auth
 modules/pyinaturalist.converters
 modules/pyinaturalist.exceptions
 modules/pyinaturalist.formatters
-modules/pyinaturalist.paginator
 modules/pyinaturalist.request_params
-modules/pyinaturalist.session
 ```

docs/user_guide/authentication.md

@@ -217,7 +217,7 @@ Direct keyring integration is provided via [python keyring](https://github.com/j
 
 To store your credentials in the keyring, run {py:func}`.set_keyring_credentials`:
 ```python
->>> from pyinaturalist.auth import set_keyring_credentials
+>>> from pyinaturalist import set_keyring_credentials
 >>> set_keyring_credentials(
 >>>     username='my_inaturalist_username',
 >>>     password='my_inaturalist_password',

pyinaturalist/__init__.py

@@ -1,14 +1,10 @@
 # ruff: noqa: F401, F403
 # isort: skip_file
-from pyinaturalist.auth import get_access_token, get_access_token_via_auth_code
-from pyinaturalist.oauth_callback import build_authorize_url, get_auth_code_via_server
-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/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/client.py pyinaturalist/client/client.pypyinaturalist/client.py renamed to pyinaturalist/client/client.py

@@ -11,7 +11,13 @@
 
 from requests import HTTPError
 
-from pyinaturalist.auth import _decode_jwt_exp, get_access_token, get_access_token_via_auth_code
+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,
@@ -26,9 +32,7 @@
 )
 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)
 

pyinaturalist/auth.py pyinaturalist/client/oauth.pypyinaturalist/auth.py renamed to pyinaturalist/client/oauth.py

@@ -11,18 +11,18 @@
 from keyring.errors import KeyringError
 from requests import HTTPError, Response
 
-from pyinaturalist.constants import API_V0, API_V1, KEYRING_KEY
-from pyinaturalist.exceptions import AuthenticationError
-from pyinaturalist.oauth_callback import (
+from pyinaturalist.client.oauth_callback import (
     _build_token_payload,
     _generate_pkce_pair,
     _obtain_auth_code,
     _resolve_auth_code_creds,
     build_authorize_url,
 )
-from pyinaturalist.session import ClientSession, get_local_session
+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__)
+_logger = getLogger(__name__)
 
 
 def _decode_jwt_exp(token: str) -> datetime | None:
@@ -115,7 +115,7 @@ def get_access_token(
     if not all(payload.values()):
         payload.update(get_keyring_credentials())
         if all(payload.values()):
-            logger.info('Retrieved credentials from keyring')
+            _logger.info('Retrieved credentials from keyring')
         else:
             raise AuthenticationError('Not all authentication parameters were provided')
 
@@ -251,7 +251,7 @@ def _get_cached_jwt(refresh: bool) -> tuple[ClientSession, str | None]:
     session = get_local_session()
     response = _get_jwt(session, only_if_cached=True)
     if response.ok and not refresh:
-        logger.info('Using cached access token')
+        _logger.info('Using cached access token')
         return session, response.json()['api_token']
     return session, None
 
@@ -280,7 +280,7 @@ def get_keyring_credentials() -> dict[str, str | None]:
             'client_secret': get_password(KEYRING_KEY, 'app_secret'),
         }
     except KeyringError as e:
-        logger.warning(e)
+        _logger.warning(e)
         return {}
 
 

pyinaturalist/oauth_callback.py pyinaturalist/client/oauth_callback.pypyinaturalist/oauth_callback.py renamed to pyinaturalist/client/oauth_callback.py

@@ -19,7 +19,7 @@
 from pyinaturalist.constants import KEYRING_KEY, OAUTH_AUTHORIZE_URL
 from pyinaturalist.exceptions import AuthenticationError
 
-logger = getLogger(__name__)
+_logger = getLogger(__name__)
 
 
 def get_auth_code_via_server(
@@ -62,7 +62,7 @@ def _serve_until_result():
             try:
                 server.handle_request()
             except Exception as e:
-                logger.exception(e)
+                _logger.exception(e)
                 break
             if result.auth_code or result.auth_error:
                 break
@@ -72,7 +72,7 @@ def _serve_until_result():
     server_thread = threading.Thread(target=_serve_until_result, daemon=True)
     server_thread.start()
 
-    logger.info('Opening browser for authorization: %s', authorize_url)
+    _logger.info('Opening browser for authorization: %s', authorize_url)
     (open_url or webbrowser.open)(authorize_url)
 
     try:
@@ -141,7 +141,7 @@ def _resolve_auth_code_creds(
             if not use_pkce and not app_secret:
                 app_secret = get_password(KEYRING_KEY, 'app_secret')
         except KeyringError as e:
-            logger.warning(e)
+            _logger.warning(e)
     if not app_id:
         raise AuthenticationError('app_id is required for authorization code flow')
     if not use_pkce and not app_secret:
@@ -183,7 +183,7 @@ def _obtain_auth_code(
 ) -> str:
     """Open the browser and obtain an authorization code via OOB or local server."""
     if use_oob:
-        logger.info('Opening browser for authorization: %s', authorize_url)
+        _logger.info('Opening browser for authorization: %s', authorize_url)
         (open_url or webbrowser.open)(authorize_url)
         if get_code:
             return get_code(authorize_url)
@@ -272,7 +272,7 @@ def do_GET(self):
                 )
 
         def log_message(self, format: str, *args: object):
-            """Route HTTP server logs through the module logger."""
-            logger.debug(format, *args)
+            """Route HTTP server logs through the module _logger."""
+            _logger.debug(format, *args)
 
     return _OAuthCallbackHandler, result

pyinaturalist/paginator.py pyinaturalist/client/paginator.pypyinaturalist/paginator.py renamed to pyinaturalist/client/paginator.py

@@ -25,7 +25,7 @@
 )
 from pyinaturalist.models import T
 
-logger = getLogger(__name__)
+_logger = getLogger(__name__)
 
 
 # TODO: Add per-endpoint 'max_per_page' parameter to use with Paginator.all()
@@ -69,7 +69,7 @@ def __init__(
             log_kwargs = {
                 k: v for k, v in self.request_kwargs.items() if k not in ['session', 'access_token']
             }
-            logger.debug(
+            _logger.debug(
                 f'Prepared paginated request: {self.request_function.__name__}'
                 f'(args={self.request_args}, kwargs={log_kwargs})'
             )
@@ -194,13 +194,13 @@ def _estimate(self):
         """
         total_requests = ceil(self.total_results / self.per_page)
         est_delay = ceil((total_requests / REQUESTS_PER_MINUTE) * 60) - 1
-        logger.info(
+        _logger.info(
             f'This query will fetch {self.total_results} results in {total_requests} requests. '
             f'Estimated total request time: {est_delay} seconds'
         )
 
         if self.total_results > LARGE_REQUEST_WARNING:
-            logger.warning(
+            _logger.warning(
                 'This request is larger than recommended for API usage. For bulk requests, consider '
                 f'using the iNat export tool instead: {EXPORT_URL}'
             )