almaapitk 0.3.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
almaapitk/__init__.py ADDED
@@ -0,0 +1,112 @@
1
+ # =============================================================================
2
+ # almaapitk - Public API Surface (API Contract v0.2.0)
3
+ # =============================================================================
4
+ #
5
+ # This is the ONLY supported public API surface for the AlmaAPITK package.
6
+ # All consumer code should import from this module only.
7
+ #
8
+ # USAGE:
9
+ # import almaapitk
10
+ # client = almaapitk.AlmaAPIClient('SANDBOX')
11
+ #
12
+ # # Or import specific symbols:
13
+ # from almaapitk import AlmaAPIClient, AlmaAPIError
14
+ #
15
+ # # Domain classes (new in v0.2.0):
16
+ # from almaapitk import Admin, Users, Acquisitions
17
+ #
18
+ # PUBLIC API (__all__):
19
+ # Core:
20
+ # - __version__: Package version string
21
+ # - AlmaAPIClient: Main API client for Alma interactions
22
+ # - AlmaResponse: Response wrapper with .data, .json(), .success properties
23
+ # - AlmaAPIError: Base exception for API errors
24
+ # - AlmaValidationError: Exception for validation failures
25
+ #
26
+ # Domains (new in v0.2.0):
27
+ # - Admin: Set management (BIB_MMS and USER sets)
28
+ # - Users: User management and email operations
29
+ # - BibliographicRecords: Bibliographic record operations
30
+ # - Acquisitions: Invoice management and POL operations
31
+ # - ResourceSharing: Lending/borrowing requests via Partners API
32
+ #
33
+ # INTERNAL (not part of public API - may change without notice):
34
+ # - src.client.* - Use almaapitk.AlmaAPIClient instead
35
+ # - src.domains.* - Use almaapitk domain classes instead
36
+ # - src.utils.* - Utility modules (project-level, not part of public API)
37
+ # - src.alma_logging.* - Logging infrastructure (internal)
38
+ #
39
+ # MIGRATION:
40
+ # If you currently import from internal modules, please migrate:
41
+ # OLD: from src.client.AlmaAPIClient import AlmaAPIClient
42
+ # NEW: from almaapitk import AlmaAPIClient
43
+ #
44
+ # OLD: from src.domains.admin import Admin
45
+ # NEW: from almaapitk import Admin
46
+ #
47
+ # OLD: from src.domains.acquisition import Acquisitions
48
+ # NEW: from almaapitk import Acquisitions
49
+ #
50
+ # IMPLEMENTATION NOTE:
51
+ # This module uses lazy imports via the _internal namespace to decouple the
52
+ # public API from the internal implementation layout. The actual class loading
53
+ # happens on first attribute access, avoiding circular import issues with
54
+ # stdlib logging.
55
+ #
56
+ # =============================================================================
57
+
58
+ __version__ = "0.3.1"
59
+
60
+ __all__ = [
61
+ # Package metadata
62
+ "__version__",
63
+ # Core client and response
64
+ "AlmaAPIClient",
65
+ "AlmaResponse",
66
+ "AlmaAPIError",
67
+ "AlmaValidationError",
68
+ # Domain classes
69
+ "Admin",
70
+ "Users",
71
+ "BibliographicRecords",
72
+ "Acquisitions",
73
+ "ResourceSharing",
74
+ "Analytics",
75
+ # Utilities
76
+ "TSVGenerator",
77
+ "CitationMetadataError",
78
+ ]
79
+
80
+ # Lazy import implementation to avoid circular import at module load time
81
+ # The actual imports happen on first attribute access
82
+ _lazy_imports = {
83
+ # Core
84
+ "AlmaAPIClient": ("almaapitk._internal", "AlmaAPIClient"),
85
+ "AlmaResponse": ("almaapitk._internal", "AlmaResponse"),
86
+ "AlmaAPIError": ("almaapitk._internal", "AlmaAPIError"),
87
+ "AlmaValidationError": ("almaapitk._internal", "AlmaValidationError"),
88
+ # Domains
89
+ "Admin": ("almaapitk._internal", "Admin"),
90
+ "Users": ("almaapitk._internal", "Users"),
91
+ "BibliographicRecords": ("almaapitk._internal", "BibliographicRecords"),
92
+ "Acquisitions": ("almaapitk._internal", "Acquisitions"),
93
+ "ResourceSharing": ("almaapitk._internal", "ResourceSharing"),
94
+ "Analytics": ("almaapitk._internal", "Analytics"),
95
+ # Utilities
96
+ "TSVGenerator": ("almaapitk.utils.tsv_generator", "TSVGenerator"),
97
+ "CitationMetadataError": ("almaapitk.utils.citation_metadata", "CitationMetadataError"),
98
+ }
99
+
100
+ _loaded = {}
101
+
102
+
103
+ def __getattr__(name):
104
+ """Lazy import handler for public API symbols."""
105
+ if name in _lazy_imports:
106
+ if name not in _loaded:
107
+ module_path, attr_name = _lazy_imports[name]
108
+ import importlib
109
+ module = importlib.import_module(module_path)
110
+ _loaded[name] = getattr(module, attr_name)
111
+ return _loaded[name]
112
+ raise AttributeError(f"module 'almaapitk' has no attribute '{name}'")
@@ -0,0 +1,39 @@
1
+ """
2
+ Internal namespace for almaapitk public API symbols.
3
+
4
+ This module aggregates all public symbols from the internal re-export modules.
5
+ It serves as an abstraction layer between the public API (almaapitk) and the
6
+ actual implementation modules (src.client.*, src.domains.*).
7
+
8
+ WARNING: This is an internal module. Do not import from here directly.
9
+ Use `from almaapitk import ...` instead.
10
+ """
11
+ # Core client and response classes
12
+ from .client import AlmaAPIClient
13
+ from .response import AlmaResponse
14
+ from .exceptions import AlmaAPIError, AlmaValidationError
15
+
16
+ # Domain classes
17
+ from .domains import (
18
+ Admin,
19
+ Users,
20
+ BibliographicRecords,
21
+ Acquisitions,
22
+ ResourceSharing,
23
+ Analytics,
24
+ )
25
+
26
+ __all__ = [
27
+ # Core
28
+ "AlmaAPIClient",
29
+ "AlmaResponse",
30
+ "AlmaAPIError",
31
+ "AlmaValidationError",
32
+ # Domains
33
+ "Admin",
34
+ "Users",
35
+ "BibliographicRecords",
36
+ "Acquisitions",
37
+ "ResourceSharing",
38
+ "Analytics",
39
+ ]
@@ -0,0 +1,9 @@
1
+ """
2
+ Internal re-export module for AlmaAPIClient.
3
+
4
+ This module is part of the internal namespace and should not be imported directly.
5
+ Use `from almaapitk import AlmaAPIClient` instead.
6
+ """
7
+ from almaapitk.client.AlmaAPIClient import AlmaAPIClient
8
+
9
+ __all__ = ["AlmaAPIClient"]
@@ -0,0 +1,29 @@
1
+ """
2
+ Internal re-export module for Alma domain classes.
3
+
4
+ This module is part of the internal namespace and should not be imported directly.
5
+ Use `from almaapitk import ...` instead.
6
+
7
+ Domain classes provide high-level API wrappers for specific Alma functional areas:
8
+ - Admin: Set management (BIB_MMS and USER sets)
9
+ - Users: User management and email operations
10
+ - BibliographicRecords: Bibliographic record operations
11
+ - Acquisitions: Invoice management and POL operations
12
+ - ResourceSharing: Lending/borrowing requests via Partners API
13
+ - Analytics: Analytics reports and data retrieval
14
+ """
15
+ from almaapitk.domains.admin import Admin
16
+ from almaapitk.domains.users import Users
17
+ from almaapitk.domains.bibs import BibliographicRecords
18
+ from almaapitk.domains.acquisition import Acquisitions
19
+ from almaapitk.domains.resource_sharing import ResourceSharing
20
+ from almaapitk.domains.analytics import Analytics
21
+
22
+ __all__ = [
23
+ "Admin",
24
+ "Users",
25
+ "BibliographicRecords",
26
+ "Acquisitions",
27
+ "ResourceSharing",
28
+ "Analytics",
29
+ ]
@@ -0,0 +1,9 @@
1
+ """
2
+ Internal re-export module for Alma exceptions.
3
+
4
+ This module is part of the internal namespace and should not be imported directly.
5
+ Use `from almaapitk import AlmaAPIError, AlmaValidationError` instead.
6
+ """
7
+ from almaapitk.client.AlmaAPIClient import AlmaAPIError, AlmaValidationError
8
+
9
+ __all__ = ["AlmaAPIError", "AlmaValidationError"]
@@ -0,0 +1,9 @@
1
+ """
2
+ Internal re-export module for AlmaResponse.
3
+
4
+ This module is part of the internal namespace and should not be imported directly.
5
+ Use `from almaapitk import AlmaResponse` instead.
6
+ """
7
+ from almaapitk.client.AlmaAPIClient import AlmaResponse
8
+
9
+ __all__ = ["AlmaResponse"]
@@ -0,0 +1,58 @@
1
+ """
2
+ AlmaAPITK Logging Module
3
+
4
+ Comprehensive logging infrastructure for API requests, responses, errors, and performance.
5
+
6
+ Components:
7
+ - logger: Main logger class for domain-specific logging
8
+ - formatters: JSON and text formatters for log output
9
+ - handlers: File handlers with rotation support
10
+ - config: Configuration management for logging settings
11
+
12
+ Usage:
13
+ from almaapitk.alma_logging import get_logger
14
+
15
+ logger = get_logger('acquisitions', environment='SANDBOX')
16
+ logger.info("Creating invoice", invoice_number="INV-001")
17
+
18
+ Features:
19
+ - Automatic API key redaction
20
+ - Request/response logging
21
+ - Error tracking with context
22
+ - Performance metrics
23
+ - Log rotation
24
+ - JSON formatted logs
25
+
26
+ Security:
27
+ - All logs are stored in logs/ directory (gitignored)
28
+ - Sensitive data (API keys, passwords, tokens) automatically redacted
29
+ - Never committed to version control
30
+
31
+ See: docs/alma_logging/LOGGING_IMPLEMENTATION_PLAN.md for complete documentation
32
+ """
33
+
34
+ __version__ = '1.0.0'
35
+ __author__ = 'AlmaAPITK Development Team'
36
+
37
+ # Phase 1: Infrastructure - skeleton implementations available
38
+ from .logger import AlmaLogger, get_logger
39
+ from .formatters import JSONFormatter, TextFormatter, redact_sensitive_data
40
+ from .handlers import AlmaRotatingFileHandler, DateOrganizedFileHandler, create_log_directory_structure
41
+ from .config import LoggingConfig, load_config
42
+
43
+ __all__ = [
44
+ # Core logging
45
+ 'AlmaLogger',
46
+ 'get_logger',
47
+ # Formatters
48
+ 'JSONFormatter',
49
+ 'TextFormatter',
50
+ 'redact_sensitive_data',
51
+ # Handlers
52
+ 'AlmaRotatingFileHandler',
53
+ 'DateOrganizedFileHandler',
54
+ 'create_log_directory_structure',
55
+ # Configuration
56
+ 'LoggingConfig',
57
+ 'load_config',
58
+ ]
@@ -0,0 +1,245 @@
1
+ """
2
+ Logging Configuration Management for AlmaAPITK
3
+
4
+ Provides configuration loading and management for the logging system.
5
+ This is a placeholder implementation for Phase 1.3.
6
+
7
+ Features (to be implemented):
8
+ - Load configuration from JSON files
9
+ - Environment-specific settings (SANDBOX/PRODUCTION)
10
+ - Domain-specific log level configuration
11
+ - Log rotation settings
12
+ - Redaction pattern configuration
13
+ """
14
+
15
+ import json
16
+ from pathlib import Path
17
+ from typing import Dict, Any, Optional, List
18
+
19
+
20
+ class LoggingConfig:
21
+ """
22
+ Configuration manager for AlmaAPITK logging.
23
+
24
+ Loads and manages logging configuration from JSON files or defaults.
25
+
26
+ Attributes:
27
+ config: Dictionary containing logging configuration
28
+ log_level: Global log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
29
+ domains: Domain-specific configuration
30
+ rotation: Log rotation settings
31
+ redact_patterns: Patterns for sensitive data redaction
32
+ """
33
+
34
+ # Default configuration
35
+ DEFAULT_CONFIG = {
36
+ "log_level": "INFO",
37
+ "domains": {
38
+ "acquisitions": {
39
+ "enabled": True,
40
+ "level": "DEBUG",
41
+ "log_requests": True,
42
+ "log_responses": True
43
+ },
44
+ "users": {
45
+ "enabled": True,
46
+ "level": "INFO",
47
+ "log_requests": True,
48
+ "log_responses": True
49
+ },
50
+ "bibs": {
51
+ "enabled": True,
52
+ "level": "INFO",
53
+ "log_requests": True,
54
+ "log_responses": True
55
+ },
56
+ "admin": {
57
+ "enabled": True,
58
+ "level": "INFO",
59
+ "log_requests": True,
60
+ "log_responses": True
61
+ },
62
+ "api_client": {
63
+ "enabled": True,
64
+ "level": "DEBUG",
65
+ "log_requests": True,
66
+ "log_responses": True
67
+ }
68
+ },
69
+ "rotation": {
70
+ "max_bytes": 10485760, # 10MB
71
+ "backup_count": 10
72
+ },
73
+ "redact_patterns": [
74
+ "apikey",
75
+ "api_key",
76
+ "password",
77
+ "token",
78
+ "secret",
79
+ "authorization"
80
+ ],
81
+ "output": {
82
+ "console": True,
83
+ "file": True,
84
+ "format": "json" # or "text"
85
+ }
86
+ }
87
+
88
+ def __init__(self, config_path: Optional[str] = None):
89
+ """
90
+ Initialize configuration manager.
91
+
92
+ Args:
93
+ config_path: Path to JSON configuration file (optional)
94
+ If not provided, uses default configuration
95
+ """
96
+ if config_path and Path(config_path).exists():
97
+ self.config = self._load_from_file(config_path)
98
+ else:
99
+ self.config = self.DEFAULT_CONFIG.copy()
100
+
101
+ # Extract commonly used settings
102
+ self.log_level = self.config.get("log_level", "INFO")
103
+ self.domains = self.config.get("domains", {})
104
+ self.rotation = self.config.get("rotation", {})
105
+ self.redact_patterns = self.config.get("redact_patterns", [])
106
+ self.output = self.config.get("output", {})
107
+
108
+ def _load_from_file(self, config_path: str) -> Dict[str, Any]:
109
+ """
110
+ Load configuration from JSON file.
111
+
112
+ Args:
113
+ config_path: Path to JSON configuration file
114
+
115
+ Returns:
116
+ Configuration dictionary
117
+ """
118
+ # TODO: Phase 1.3 - Implement file loading with error handling
119
+ # TODO: Phase 1.3 - Validate configuration structure
120
+ # TODO: Phase 1.3 - Merge with defaults for missing keys
121
+ with open(config_path, 'r') as f:
122
+ return json.load(f)
123
+
124
+ def get_domain_config(self, domain: str) -> Dict[str, Any]:
125
+ """
126
+ Get configuration for specific domain.
127
+
128
+ Args:
129
+ domain: Domain name (acquisitions, users, bibs, admin)
130
+
131
+ Returns:
132
+ Domain-specific configuration dictionary
133
+ """
134
+ return self.domains.get(domain, {
135
+ "enabled": True,
136
+ "level": self.log_level,
137
+ "log_requests": True,
138
+ "log_responses": True
139
+ })
140
+
141
+ def is_domain_enabled(self, domain: str) -> bool:
142
+ """
143
+ Check if logging is enabled for domain.
144
+
145
+ Args:
146
+ domain: Domain name
147
+
148
+ Returns:
149
+ True if logging enabled for this domain
150
+ """
151
+ domain_config = self.get_domain_config(domain)
152
+ return domain_config.get("enabled", True)
153
+
154
+ def get_domain_level(self, domain: str) -> str:
155
+ """
156
+ Get log level for specific domain.
157
+
158
+ Args:
159
+ domain: Domain name
160
+
161
+ Returns:
162
+ Log level string (DEBUG, INFO, WARNING, ERROR, CRITICAL)
163
+ """
164
+ domain_config = self.get_domain_config(domain)
165
+ return domain_config.get("level", self.log_level)
166
+
167
+ def should_log_requests(self, domain: str) -> bool:
168
+ """
169
+ Check if request logging is enabled for domain.
170
+
171
+ Args:
172
+ domain: Domain name
173
+
174
+ Returns:
175
+ True if request logging enabled
176
+ """
177
+ domain_config = self.get_domain_config(domain)
178
+ return domain_config.get("log_requests", True)
179
+
180
+ def should_log_responses(self, domain: str) -> bool:
181
+ """
182
+ Check if response logging is enabled for domain.
183
+
184
+ Args:
185
+ domain: Domain name
186
+
187
+ Returns:
188
+ True if response logging enabled
189
+ """
190
+ domain_config = self.get_domain_config(domain)
191
+ return domain_config.get("log_responses", True)
192
+
193
+ def get_redact_patterns(self) -> List[str]:
194
+ """
195
+ Get list of patterns for sensitive data redaction.
196
+
197
+ Returns:
198
+ List of field name patterns to redact
199
+ """
200
+ return self.redact_patterns
201
+
202
+ def get_rotation_settings(self) -> Dict[str, int]:
203
+ """
204
+ Get log rotation settings.
205
+
206
+ Returns:
207
+ Dictionary with max_bytes and backup_count
208
+ """
209
+ return {
210
+ "max_bytes": self.rotation.get("max_bytes", 10485760),
211
+ "backup_count": self.rotation.get("backup_count", 10)
212
+ }
213
+
214
+ def save_to_file(self, config_path: str):
215
+ """
216
+ Save current configuration to JSON file.
217
+
218
+ Args:
219
+ config_path: Path where to save configuration
220
+ """
221
+ # TODO: Phase 1.3 - Implement configuration saving
222
+ # TODO: Phase 1.3 - Pretty-print JSON with indentation
223
+ with open(config_path, 'w') as f:
224
+ json.dump(self.config, f, indent=2)
225
+
226
+
227
+ def load_config(config_path: Optional[str] = None) -> LoggingConfig:
228
+ """
229
+ Load logging configuration.
230
+
231
+ Args:
232
+ config_path: Path to configuration file (optional)
233
+
234
+ Returns:
235
+ LoggingConfig instance
236
+
237
+ Example:
238
+ >>> config = load_config('config/logging_config.json')
239
+ >>> config.get_domain_level('acquisitions')
240
+ 'DEBUG'
241
+ """
242
+ return LoggingConfig(config_path)
243
+
244
+
245
+ __all__ = ['LoggingConfig', 'load_config']