atlan-application-sdk-api 3.51.0__tar.gz

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.
Files changed (81) hide show
  1. atlan_application_sdk_api-3.51.0/.gitignore +203 -0
  2. atlan_application_sdk_api-3.51.0/PKG-INFO +230 -0
  3. atlan_application_sdk_api-3.51.0/README.md +194 -0
  4. atlan_application_sdk_api-3.51.0/api-files.txt +78 -0
  5. atlan_application_sdk_api-3.51.0/application_sdk/__init__.py +7 -0
  6. atlan_application_sdk_api-3.51.0/application_sdk/_build_info.py +62 -0
  7. atlan_application_sdk_api-3.51.0/application_sdk/_context_errors.py +65 -0
  8. atlan_application_sdk_api-3.51.0/application_sdk/_install.py +130 -0
  9. atlan_application_sdk_api-3.51.0/application_sdk/_logging.py +171 -0
  10. atlan_application_sdk_api-3.51.0/application_sdk/_runtime/__init__.py +29 -0
  11. atlan_application_sdk_api-3.51.0/application_sdk/_runtime/offload.py +1020 -0
  12. atlan_application_sdk_api-3.51.0/application_sdk/_runtime/progress.py +757 -0
  13. atlan_application_sdk_api-3.51.0/application_sdk/clients/__init__.py +63 -0
  14. atlan_application_sdk_api-3.51.0/application_sdk/clients/_interface.py +58 -0
  15. atlan_application_sdk_api-3.51.0/application_sdk/clients/_sql_failure_classifier.py +112 -0
  16. atlan_application_sdk_api-3.51.0/application_sdk/clients/base.py +565 -0
  17. atlan_application_sdk_api-3.51.0/application_sdk/clients/http_errors.py +28 -0
  18. atlan_application_sdk_api-3.51.0/application_sdk/clients/models.py +49 -0
  19. atlan_application_sdk_api-3.51.0/application_sdk/clients/sql.py +1218 -0
  20. atlan_application_sdk_api-3.51.0/application_sdk/clients/sql_errors.py +192 -0
  21. atlan_application_sdk_api-3.51.0/application_sdk/clients/sql_typecasters.py +431 -0
  22. atlan_application_sdk_api-3.51.0/application_sdk/clients/ssl_utils.py +247 -0
  23. atlan_application_sdk_api-3.51.0/application_sdk/common/__init__.py +53 -0
  24. atlan_application_sdk_api-3.51.0/application_sdk/common/_generated_tree.py +321 -0
  25. atlan_application_sdk_api-3.51.0/application_sdk/common/_listing.py +192 -0
  26. atlan_application_sdk_api-3.51.0/application_sdk/common/aws_utils.py +522 -0
  27. atlan_application_sdk_api-3.51.0/application_sdk/common/aws_utils_errors.py +88 -0
  28. atlan_application_sdk_api-3.51.0/application_sdk/common/build_identity.py +120 -0
  29. atlan_application_sdk_api-3.51.0/application_sdk/common/concurrency.py +45 -0
  30. atlan_application_sdk_api-3.51.0/application_sdk/common/errors.py +99 -0
  31. atlan_application_sdk_api-3.51.0/application_sdk/common/filter_matching.py +261 -0
  32. atlan_application_sdk_api-3.51.0/application_sdk/common/logger.py +11 -0
  33. atlan_application_sdk_api-3.51.0/application_sdk/common/models.py +31 -0
  34. atlan_application_sdk_api-3.51.0/application_sdk/common/sql_filters.py +719 -0
  35. atlan_application_sdk_api-3.51.0/application_sdk/common/sql_filters_errors.py +17 -0
  36. atlan_application_sdk_api-3.51.0/application_sdk/common/task_queue.py +431 -0
  37. atlan_application_sdk_api-3.51.0/application_sdk/common/types.py +51 -0
  38. atlan_application_sdk_api-3.51.0/application_sdk/common/utils.py +87 -0
  39. atlan_application_sdk_api-3.51.0/application_sdk/constants.py +1120 -0
  40. atlan_application_sdk_api-3.51.0/application_sdk/contracts/__init__.py +158 -0
  41. atlan_application_sdk_api-3.51.0/application_sdk/contracts/base.py +1178 -0
  42. atlan_application_sdk_api-3.51.0/application_sdk/contracts/events.py +251 -0
  43. atlan_application_sdk_api-3.51.0/application_sdk/contracts/types.py +801 -0
  44. atlan_application_sdk_api-3.51.0/application_sdk/contracts/types_errors.py +17 -0
  45. atlan_application_sdk_api-3.51.0/application_sdk/credentials/__init__.py +326 -0
  46. atlan_application_sdk_api-3.51.0/application_sdk/credentials/errors.py +226 -0
  47. atlan_application_sdk_api-3.51.0/application_sdk/credentials/extra.py +114 -0
  48. atlan_application_sdk_api-3.51.0/application_sdk/credentials/ingress.py +283 -0
  49. atlan_application_sdk_api-3.51.0/application_sdk/credentials/ref.py +376 -0
  50. atlan_application_sdk_api-3.51.0/application_sdk/credentials/spec.py +182 -0
  51. atlan_application_sdk_api-3.51.0/application_sdk/credentials/types.py +339 -0
  52. atlan_application_sdk_api-3.51.0/application_sdk/credentials/utils.py +257 -0
  53. atlan_application_sdk_api-3.51.0/application_sdk/errors/__init__.py +224 -0
  54. atlan_application_sdk_api-3.51.0/application_sdk/errors/base.py +504 -0
  55. atlan_application_sdk_api-3.51.0/application_sdk/errors/categories.py +118 -0
  56. atlan_application_sdk_api-3.51.0/application_sdk/errors/http.py +81 -0
  57. atlan_application_sdk_api-3.51.0/application_sdk/errors/leaves.py +526 -0
  58. atlan_application_sdk_api-3.51.0/application_sdk/errors/wire.py +124 -0
  59. atlan_application_sdk_api-3.51.0/application_sdk/handler/__init__.py +97 -0
  60. atlan_application_sdk_api-3.51.0/application_sdk/handler/_warmup.py +198 -0
  61. atlan_application_sdk_api-3.51.0/application_sdk/handler/asgi.py +252 -0
  62. atlan_application_sdk_api-3.51.0/application_sdk/handler/base.py +281 -0
  63. atlan_application_sdk_api-3.51.0/application_sdk/handler/context.py +212 -0
  64. atlan_application_sdk_api-3.51.0/application_sdk/handler/contracts.py +1166 -0
  65. atlan_application_sdk_api-3.51.0/application_sdk/handler/manifest.py +81 -0
  66. atlan_application_sdk_api-3.51.0/application_sdk/handler/metadata_routes.py +699 -0
  67. atlan_application_sdk_api-3.51.0/application_sdk/handler/object_routes.py +418 -0
  68. atlan_application_sdk_api-3.51.0/application_sdk/handler/request_contract.py +91 -0
  69. atlan_application_sdk_api-3.51.0/application_sdk/handler/routes.py +1118 -0
  70. atlan_application_sdk_api-3.51.0/application_sdk/handler/service_errors.py +37 -0
  71. atlan_application_sdk_api-3.51.0/application_sdk/server/__init__.py +15 -0
  72. atlan_application_sdk_api-3.51.0/application_sdk/server/fastapi/models.py +338 -0
  73. atlan_application_sdk_api-3.51.0/application_sdk/templates/__init__.py +52 -0
  74. atlan_application_sdk_api-3.51.0/application_sdk/templates/contracts/__init__.py +111 -0
  75. atlan_application_sdk_api-3.51.0/application_sdk/templates/contracts/base_metadata_extraction.py +32 -0
  76. atlan_application_sdk_api-3.51.0/application_sdk/templates/contracts/incremental_sql.py +563 -0
  77. atlan_application_sdk_api-3.51.0/application_sdk/templates/contracts/sql_metadata.py +824 -0
  78. atlan_application_sdk_api-3.51.0/application_sdk/templates/contracts/sql_query.py +105 -0
  79. atlan_application_sdk_api-3.51.0/application_sdk/version.py +40 -0
  80. atlan_application_sdk_api-3.51.0/hatch_build.py +37 -0
  81. atlan_application_sdk_api-3.51.0/pyproject.toml +103 -0
@@ -0,0 +1,203 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ # Distribution / packaging
10
+ .Python
11
+ build/
12
+ develop-eggs/
13
+ dist/
14
+ downloads/
15
+ eggs/
16
+ .eggs/
17
+ lib/
18
+ lib64/
19
+ parts/
20
+ sdist/
21
+ var/
22
+ wheels/
23
+ share/python-wheels/
24
+ *.egg-info/
25
+ .installed.cfg
26
+ *.egg
27
+
28
+
29
+ # PyInstaller
30
+ # Usually these files are written by a python script from a template
31
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
32
+ *.spec
33
+
34
+ # Installer logs
35
+ pip-log.txt
36
+ pip-delete-this-directory.txt
37
+
38
+ # Unit test / coverage reports
39
+ htmlcov/
40
+ .tox/
41
+ .nox/
42
+ .coverage
43
+ .coverage.*
44
+ .cache
45
+ nosetests.xml
46
+ coverage.xml
47
+ *.cover
48
+ *.py,cover
49
+ .hypothesis/
50
+ .pytest_cache/
51
+ cover/
52
+
53
+ # Translations
54
+ *.mo
55
+ *.pot
56
+
57
+ # Django stuff:
58
+ *.log
59
+ local_settings.py
60
+ db.sqlite3
61
+ db.sqlite3-journal
62
+
63
+ # Flask stuff:
64
+ instance/
65
+ .webassets-cache
66
+
67
+ # Scrapy stuff:
68
+ .scrapy
69
+
70
+ # Sphinx documentation
71
+ docs/_build/
72
+
73
+ # PyBuilder
74
+ .pybuilder/
75
+ target/
76
+
77
+ # Jupyter Notebook
78
+ .ipynb_checkpoints
79
+
80
+ # IPython
81
+ profile_default/
82
+ ipython_config.py
83
+
84
+ # pyenv
85
+ # For a library or package, you might want to ignore these files since the code is
86
+ # intended to run in multiple environments; otherwise, check them in:
87
+ # .python-version
88
+
89
+ # pipenv
90
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
91
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
92
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
93
+ # install all needed dependencies.
94
+ #Pipfile.lock
95
+
96
+ # pdm
97
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
98
+ #pdm.lock
99
+ # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
100
+ # in version control.
101
+ # https://pdm.fming.dev/latest/usage/project/#working-with-version-control
102
+ .pdm.toml
103
+ .pdm-python
104
+ .pdm-build/
105
+
106
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
107
+ __pypackages__/
108
+
109
+ # Celery stuff
110
+ celerybeat-schedule
111
+ celerybeat.pid
112
+
113
+ # SageMath parsed files
114
+ *.sage.py
115
+
116
+ # Environments
117
+ .env
118
+ .venv
119
+ env/
120
+ venv/
121
+ ENV/
122
+ env.bak/
123
+ venv.bak/
124
+
125
+ # Spyder project settings
126
+ .spyderproject
127
+ .spyproject
128
+
129
+ # Rope project settings
130
+ .ropeproject
131
+
132
+ # mkdocs documentation
133
+ docs/site
134
+
135
+ # mypy
136
+ .mypy_cache/
137
+ .dmypy.json
138
+ dmypy.json
139
+
140
+ # Pyre type checker
141
+ .pyre/
142
+
143
+ # pytype static type analyzer
144
+ .pytype/
145
+
146
+ # Cython debug symbols
147
+ cython_debug/
148
+
149
+ # PyCharm
150
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
151
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
152
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
153
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
154
+ .idea/
155
+ .atlan
156
+
157
+ workflow_status.md
158
+
159
+ # Scale data generator
160
+ output
161
+ docs/reference/*.rst
162
+ .DS_Store
163
+
164
+ # Interrogate coverage report
165
+ docstring-cov.md
166
+
167
+ # vscode settings
168
+ .vscode
169
+
170
+ # local
171
+ local/
172
+ temporal.db
173
+
174
+ # Claude Code worktrees
175
+ .claude/worktrees/
176
+
177
+ # Claude Code plans (local working files, not for version control)
178
+ .claude/plans/
179
+ # >>> atlan-builders >>>
180
+ # Managed by atlan-core — edit inside this block and it will be preserved
181
+ # only until the next bootstrap tick. Add your own rules outside the block.
182
+ .atlan/journal/pending.jsonl
183
+ .atlan/journal/.drafts/
184
+ .atlan/cache/
185
+ # <<< atlan-builders <<<
186
+
187
+ # Claude Code runtime lock files
188
+ .claude/scheduled_tasks.lock
189
+
190
+ # Remediation run artifacts
191
+ remediation/node_modules/
192
+ remediation/runs/
193
+
194
+ # Renovate setup
195
+ renovate-config/README.md
196
+
197
+ # CI scratch: the sdr-e2e composite writes test output, container logs and the
198
+ # harness evidence bundle here, then uploads the directory as an artifact.
199
+ results/
200
+
201
+ # Built into the conformance wheel from the repo-root contract_schema.lock.json
202
+ # (FND-3108); the root file is the only committed SDK ledger.
203
+ packages/conformance/conformance/data/contract_schema.lock.json
@@ -0,0 +1,230 @@
1
+ Metadata-Version: 2.5
2
+ Name: atlan-application-sdk-api
3
+ Version: 3.51.0
4
+ Summary: Experimental: the handler surface of the Atlan Application SDK, for the consolidated API host
5
+ Project-URL: Homepage, https://github.com/atlanhq/application-sdk
6
+ Project-URL: Source, https://github.com/atlanhq/application-sdk/tree/main/packages/api
7
+ Project-URL: Documentation, https://github.com/atlanhq/application-sdk/blob/main/docs/standards/api-distribution.md
8
+ Project-URL: Changelog, https://github.com/atlanhq/application-sdk/blob/main/CHANGELOG.md
9
+ Author-email: Atlan App Team <connect@atlan.com>
10
+ License-Expression: Apache-2.0
11
+ Keywords: api,atlan,handler,sdk
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: Apache Software License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Requires-Python: >=3.11
18
+ Requires-Dist: fastapi<0.144.0,>=0.143.0
19
+ Requires-Dist: httpx<0.29.0,>=0.27.0
20
+ Requires-Dist: orjson<4.0.0,>=3.11.6
21
+ Requires-Dist: pydantic<3.0.0,>=2.10.6
22
+ Requires-Dist: python-multipart>=0.0.26
23
+ Provides-Extra: aws
24
+ Requires-Dist: boto3<2.0.0,>=1.38.6; extra == 'aws'
25
+ Requires-Dist: httpx<0.29.0,>=0.27.0; extra == 'aws'
26
+ Requires-Dist: python-dotenv<2.0.0,>=1.1.0; extra == 'aws'
27
+ Provides-Extra: pandas
28
+ Requires-Dist: pandas<3.0.0,>=2.2.3; extra == 'pandas'
29
+ Provides-Extra: pyatlan
30
+ Requires-Dist: pyatlan<12,>=11.3; extra == 'pyatlan'
31
+ Provides-Extra: sql
32
+ Requires-Dist: httpx<0.29.0,>=0.27.0; extra == 'sql'
33
+ Requires-Dist: python-dotenv<2.0.0,>=1.1.0; extra == 'sql'
34
+ Requires-Dist: sqlalchemy[asyncio]<3.0.0,>=2.0.36; extra == 'sql'
35
+ Description-Content-Type: text/markdown
36
+
37
+ # atlan-application-sdk-api
38
+
39
+ > **Experimental.** The contents of this package and how it is built may change
40
+ > between releases. If you are building an Atlan app, depend on
41
+ > [`atlan-application-sdk`](https://pypi.org/project/atlan-application-sdk/),
42
+ > which installs this package for you.
43
+
44
+ The **handler** part of the
45
+ [Atlan Application SDK](https://github.com/atlanhq/application-sdk), packaged
46
+ on its own.
47
+
48
+ An Atlan app has two halves:
49
+
50
+ - a **worker**, which runs the app's workflows (extraction, publishing) on
51
+ Temporal and Dapr;
52
+ - a **handler**, a small HTTP service that answers Atlan while a user sets up a
53
+ connection: *do these credentials work?*, *is the source ready?*, *which
54
+ databases and schemas can I pick?*
55
+
56
+ This package contains everything the handler needs and none of the worker
57
+ runtime. Its core dependencies are FastAPI, Pydantic, orjson, httpx and
58
+ python-multipart. That lets one lightweight process serve the handlers of many
59
+ apps.
60
+
61
+ ## Do I need this?
62
+
63
+ Usually not. `atlan-application-sdk` depends on this package at exactly the
64
+ same version, so installing the SDK gives you both, and your imports stay the
65
+ same:
66
+
67
+ ```python
68
+ from application_sdk.handler import Handler # same module either way
69
+ ```
70
+
71
+ Install this package directly only to run handlers **without** the worker
72
+ runtime, for example to serve them from a separate, smaller service.
73
+
74
+ ## Installation
75
+
76
+ ```bash
77
+ pip install atlan-application-sdk-api
78
+ # or
79
+ uv add atlan-application-sdk-api
80
+ ```
81
+
82
+ Requires Python 3.11 or newer. Add an extra when your handler uses that part of
83
+ the SDK:
84
+
85
+ | Extra | When your handler uses |
86
+ |---|---|
87
+ | `sql` | The SDK's SQL client (SQLAlchemy) |
88
+ | `aws` | The SDK's AWS helpers (boto3), or the config and file routes |
89
+ | `pandas` | Query results as pandas DataFrames |
90
+ | `pyatlan` | The Atlas conversion helpers on `ConnectionRef` |
91
+
92
+ ```bash
93
+ pip install "atlan-application-sdk-api[sql]"
94
+ ```
95
+
96
+ The extras have the same version pins as the matching extras of
97
+ `atlan-application-sdk`.
98
+
99
+ ## Quick start
100
+
101
+ Write a handler by subclassing `Handler` and implementing its three methods.
102
+ Then turn it into a FastAPI app with `build_asgi_app`:
103
+
104
+ ```python
105
+ from application_sdk.handler import (
106
+ AuthInput,
107
+ AuthOutput,
108
+ AuthStatus,
109
+ Handler,
110
+ MetadataInput,
111
+ MetadataOutput,
112
+ PreflightInput,
113
+ PreflightOutput,
114
+ PreflightStatus,
115
+ SqlMetadataOutput,
116
+ )
117
+ from application_sdk.handler.asgi import build_asgi_app
118
+
119
+
120
+ class DemoHandler(Handler):
121
+ async def test_auth(self, input: AuthInput) -> AuthOutput:
122
+ # Check input.credentials against your source.
123
+ return AuthOutput(status=AuthStatus.SUCCESS)
124
+
125
+ async def preflight_check(self, input: PreflightInput) -> PreflightOutput:
126
+ # Confirm the source is ready to be extracted.
127
+ return PreflightOutput(status=PreflightStatus.READY)
128
+
129
+ async def fetch_metadata(self, input: MetadataInput) -> MetadataOutput:
130
+ # List what the user can choose to extract.
131
+ return SqlMetadataOutput(
132
+ objects=[{"TABLE_CATALOG": "analytics", "TABLE_SCHEMA": "public"}]
133
+ )
134
+
135
+
136
+ app = build_asgi_app(DemoHandler(), app_name="demo")
137
+ ```
138
+
139
+ Serve it with any ASGI server (not included), for example
140
+ `pip install uvicorn` and then `uvicorn demo:app`:
141
+
142
+ ```bash
143
+ curl -X POST localhost:8000/workflows/v1/auth \
144
+ -H 'content-type: application/json' -d '{"credentials": []}'
145
+ # {"success": true, "data": {"status": "success", ...}, "message": "Authentication success"}
146
+ ```
147
+
148
+ ## Routes
149
+
150
+ `build_asgi_app` serves the same routes the full SDK's handler service does, so
151
+ an app answers identically from either one:
152
+
153
+ | Route | Answered by |
154
+ |---|---|
155
+ | `GET /health` | Always `{"status": "ok"}` |
156
+ | `POST /workflows/v1/auth` | `Handler.test_auth` |
157
+ | `POST /workflows/v1/check` | `Handler.preflight_check` |
158
+ | `POST /workflows/v1/metadata` | `Handler.fetch_metadata` |
159
+ | `POST /workflows/v1/warmup` | `Handler.warmup` (optional) |
160
+ | `GET /workflows/v1/configmap/{id}`, `/configmaps`, `/input-contract`, `GET`/`POST /workflows/v1/manifest` | The app's `generated/` folder, if the app package ships one |
161
+ | `GET`/`POST /workflows/v1/config/{id}`, `POST /workflows/v1/file` | An S3 bucket named by `ATLAN_S3_BUCKET` (and `ATLAN_S3_REGION`); needs the `aws` extra. These routes return 503 when it isn't set |
162
+ | Your own routes | FastAPI routers returned from `Handler.routers()`, served after the SDK's |
163
+
164
+ `build_asgi_app` takes a few keyword options:
165
+
166
+ - `app_package`: where the app's code and `generated/` folder live;
167
+ - `blocking_threads`: the size of this app's thread pool, default 8;
168
+ - `generated_dir`;
169
+ - `object_store`.
170
+
171
+ Each app built this way gets its own thread pool for `run_in_thread`, so several
172
+ apps in one process don't block each other.
173
+
174
+ ## What's included
175
+
176
+ | Module | Contents |
177
+ |---|---|
178
+ | `application_sdk.handler` | `Handler`, `HandlerContext`, and the request and response models |
179
+ | `application_sdk.handler.asgi` | `build_asgi_app` |
180
+ | `application_sdk.errors` | `AppError` and typed error classes; secrets and URL credentials are redacted from messages |
181
+ | `application_sdk.credentials` | Credential specs, types and parsing |
182
+ | `application_sdk.contracts`, `application_sdk.templates.contracts` | Input-contract models |
183
+ | `application_sdk.common.concurrency` | `run_in_thread`, for blocking calls inside async handlers |
184
+ | `application_sdk.common.logger` | `get_logger` |
185
+ | `application_sdk.clients.sql` (`sql` extra) | The SQL client base |
186
+ | `application_sdk.common.aws_utils` (`aws` extra) | AWS helpers |
187
+
188
+ The complete file list is in
189
+ [`api-files.txt`](https://github.com/atlanhq/application-sdk/blob/main/packages/api/api-files.txt).
190
+
191
+ **Not included:** Temporal, Dapr, the SDK's object-store layer, its structured
192
+ logging and telemetry, or anything else that runs workflows. That stays in
193
+ `atlan-application-sdk`.
194
+
195
+ A few handler features depend on the worker runtime. Without it they raise a
196
+ clear, typed error instead of failing on an import. For example,
197
+ `self.context.get_secret()` raises `SecretStoreNotConfiguredError` because
198
+ there is no secret store. Credentials sent with the request work normally.
199
+
200
+ ## Versioning
201
+
202
+ This package is released together with `atlan-application-sdk`, from the same
203
+ commit and always with the **same version number**. For example,
204
+ `atlan-application-sdk` 3.51.0 requires `atlan-application-sdk-api` 3.51.0.
205
+
206
+ A new version can contain the same code as the previous one when a release
207
+ changed only the worker part of the SDK.
208
+
209
+ ## Upgrading from an SDK release older than this package
210
+
211
+ Before this package existed, `atlan-application-sdk` shipped these files itself.
212
+ Upgrading across that boundary **with pip** can delete them. pip installs this
213
+ package first, then deletes the same files when it removes the old SDK.
214
+ Starting the app (`python -m application_sdk.main`) reports this and tells you
215
+ to run:
216
+
217
+ ```bash
218
+ pip install --force-reinstall --no-deps atlan-application-sdk-api
219
+ ```
220
+
221
+ uv is not affected. This only happens once; later upgrades are clean.
222
+
223
+ ## Links
224
+
225
+ - Source and documentation:
226
+ [github.com/atlanhq/application-sdk](https://github.com/atlanhq/application-sdk)
227
+ - Design notes:
228
+ [docs/standards/api-distribution.md](https://github.com/atlanhq/application-sdk/blob/main/docs/standards/api-distribution.md)
229
+ - Full SDK: [atlan-application-sdk on PyPI](https://pypi.org/project/atlan-application-sdk/)
230
+ - License: Apache-2.0
@@ -0,0 +1,194 @@
1
+ # atlan-application-sdk-api
2
+
3
+ > **Experimental.** The contents of this package and how it is built may change
4
+ > between releases. If you are building an Atlan app, depend on
5
+ > [`atlan-application-sdk`](https://pypi.org/project/atlan-application-sdk/),
6
+ > which installs this package for you.
7
+
8
+ The **handler** part of the
9
+ [Atlan Application SDK](https://github.com/atlanhq/application-sdk), packaged
10
+ on its own.
11
+
12
+ An Atlan app has two halves:
13
+
14
+ - a **worker**, which runs the app's workflows (extraction, publishing) on
15
+ Temporal and Dapr;
16
+ - a **handler**, a small HTTP service that answers Atlan while a user sets up a
17
+ connection: *do these credentials work?*, *is the source ready?*, *which
18
+ databases and schemas can I pick?*
19
+
20
+ This package contains everything the handler needs and none of the worker
21
+ runtime. Its core dependencies are FastAPI, Pydantic, orjson, httpx and
22
+ python-multipart. That lets one lightweight process serve the handlers of many
23
+ apps.
24
+
25
+ ## Do I need this?
26
+
27
+ Usually not. `atlan-application-sdk` depends on this package at exactly the
28
+ same version, so installing the SDK gives you both, and your imports stay the
29
+ same:
30
+
31
+ ```python
32
+ from application_sdk.handler import Handler # same module either way
33
+ ```
34
+
35
+ Install this package directly only to run handlers **without** the worker
36
+ runtime, for example to serve them from a separate, smaller service.
37
+
38
+ ## Installation
39
+
40
+ ```bash
41
+ pip install atlan-application-sdk-api
42
+ # or
43
+ uv add atlan-application-sdk-api
44
+ ```
45
+
46
+ Requires Python 3.11 or newer. Add an extra when your handler uses that part of
47
+ the SDK:
48
+
49
+ | Extra | When your handler uses |
50
+ |---|---|
51
+ | `sql` | The SDK's SQL client (SQLAlchemy) |
52
+ | `aws` | The SDK's AWS helpers (boto3), or the config and file routes |
53
+ | `pandas` | Query results as pandas DataFrames |
54
+ | `pyatlan` | The Atlas conversion helpers on `ConnectionRef` |
55
+
56
+ ```bash
57
+ pip install "atlan-application-sdk-api[sql]"
58
+ ```
59
+
60
+ The extras have the same version pins as the matching extras of
61
+ `atlan-application-sdk`.
62
+
63
+ ## Quick start
64
+
65
+ Write a handler by subclassing `Handler` and implementing its three methods.
66
+ Then turn it into a FastAPI app with `build_asgi_app`:
67
+
68
+ ```python
69
+ from application_sdk.handler import (
70
+ AuthInput,
71
+ AuthOutput,
72
+ AuthStatus,
73
+ Handler,
74
+ MetadataInput,
75
+ MetadataOutput,
76
+ PreflightInput,
77
+ PreflightOutput,
78
+ PreflightStatus,
79
+ SqlMetadataOutput,
80
+ )
81
+ from application_sdk.handler.asgi import build_asgi_app
82
+
83
+
84
+ class DemoHandler(Handler):
85
+ async def test_auth(self, input: AuthInput) -> AuthOutput:
86
+ # Check input.credentials against your source.
87
+ return AuthOutput(status=AuthStatus.SUCCESS)
88
+
89
+ async def preflight_check(self, input: PreflightInput) -> PreflightOutput:
90
+ # Confirm the source is ready to be extracted.
91
+ return PreflightOutput(status=PreflightStatus.READY)
92
+
93
+ async def fetch_metadata(self, input: MetadataInput) -> MetadataOutput:
94
+ # List what the user can choose to extract.
95
+ return SqlMetadataOutput(
96
+ objects=[{"TABLE_CATALOG": "analytics", "TABLE_SCHEMA": "public"}]
97
+ )
98
+
99
+
100
+ app = build_asgi_app(DemoHandler(), app_name="demo")
101
+ ```
102
+
103
+ Serve it with any ASGI server (not included), for example
104
+ `pip install uvicorn` and then `uvicorn demo:app`:
105
+
106
+ ```bash
107
+ curl -X POST localhost:8000/workflows/v1/auth \
108
+ -H 'content-type: application/json' -d '{"credentials": []}'
109
+ # {"success": true, "data": {"status": "success", ...}, "message": "Authentication success"}
110
+ ```
111
+
112
+ ## Routes
113
+
114
+ `build_asgi_app` serves the same routes the full SDK's handler service does, so
115
+ an app answers identically from either one:
116
+
117
+ | Route | Answered by |
118
+ |---|---|
119
+ | `GET /health` | Always `{"status": "ok"}` |
120
+ | `POST /workflows/v1/auth` | `Handler.test_auth` |
121
+ | `POST /workflows/v1/check` | `Handler.preflight_check` |
122
+ | `POST /workflows/v1/metadata` | `Handler.fetch_metadata` |
123
+ | `POST /workflows/v1/warmup` | `Handler.warmup` (optional) |
124
+ | `GET /workflows/v1/configmap/{id}`, `/configmaps`, `/input-contract`, `GET`/`POST /workflows/v1/manifest` | The app's `generated/` folder, if the app package ships one |
125
+ | `GET`/`POST /workflows/v1/config/{id}`, `POST /workflows/v1/file` | An S3 bucket named by `ATLAN_S3_BUCKET` (and `ATLAN_S3_REGION`); needs the `aws` extra. These routes return 503 when it isn't set |
126
+ | Your own routes | FastAPI routers returned from `Handler.routers()`, served after the SDK's |
127
+
128
+ `build_asgi_app` takes a few keyword options:
129
+
130
+ - `app_package`: where the app's code and `generated/` folder live;
131
+ - `blocking_threads`: the size of this app's thread pool, default 8;
132
+ - `generated_dir`;
133
+ - `object_store`.
134
+
135
+ Each app built this way gets its own thread pool for `run_in_thread`, so several
136
+ apps in one process don't block each other.
137
+
138
+ ## What's included
139
+
140
+ | Module | Contents |
141
+ |---|---|
142
+ | `application_sdk.handler` | `Handler`, `HandlerContext`, and the request and response models |
143
+ | `application_sdk.handler.asgi` | `build_asgi_app` |
144
+ | `application_sdk.errors` | `AppError` and typed error classes; secrets and URL credentials are redacted from messages |
145
+ | `application_sdk.credentials` | Credential specs, types and parsing |
146
+ | `application_sdk.contracts`, `application_sdk.templates.contracts` | Input-contract models |
147
+ | `application_sdk.common.concurrency` | `run_in_thread`, for blocking calls inside async handlers |
148
+ | `application_sdk.common.logger` | `get_logger` |
149
+ | `application_sdk.clients.sql` (`sql` extra) | The SQL client base |
150
+ | `application_sdk.common.aws_utils` (`aws` extra) | AWS helpers |
151
+
152
+ The complete file list is in
153
+ [`api-files.txt`](https://github.com/atlanhq/application-sdk/blob/main/packages/api/api-files.txt).
154
+
155
+ **Not included:** Temporal, Dapr, the SDK's object-store layer, its structured
156
+ logging and telemetry, or anything else that runs workflows. That stays in
157
+ `atlan-application-sdk`.
158
+
159
+ A few handler features depend on the worker runtime. Without it they raise a
160
+ clear, typed error instead of failing on an import. For example,
161
+ `self.context.get_secret()` raises `SecretStoreNotConfiguredError` because
162
+ there is no secret store. Credentials sent with the request work normally.
163
+
164
+ ## Versioning
165
+
166
+ This package is released together with `atlan-application-sdk`, from the same
167
+ commit and always with the **same version number**. For example,
168
+ `atlan-application-sdk` 3.51.0 requires `atlan-application-sdk-api` 3.51.0.
169
+
170
+ A new version can contain the same code as the previous one when a release
171
+ changed only the worker part of the SDK.
172
+
173
+ ## Upgrading from an SDK release older than this package
174
+
175
+ Before this package existed, `atlan-application-sdk` shipped these files itself.
176
+ Upgrading across that boundary **with pip** can delete them. pip installs this
177
+ package first, then deletes the same files when it removes the old SDK.
178
+ Starting the app (`python -m application_sdk.main`) reports this and tells you
179
+ to run:
180
+
181
+ ```bash
182
+ pip install --force-reinstall --no-deps atlan-application-sdk-api
183
+ ```
184
+
185
+ uv is not affected. This only happens once; later upgrades are clean.
186
+
187
+ ## Links
188
+
189
+ - Source and documentation:
190
+ [github.com/atlanhq/application-sdk](https://github.com/atlanhq/application-sdk)
191
+ - Design notes:
192
+ [docs/standards/api-distribution.md](https://github.com/atlanhq/application-sdk/blob/main/docs/standards/api-distribution.md)
193
+ - Full SDK: [atlan-application-sdk on PyPI](https://pypi.org/project/atlan-application-sdk/)
194
+ - License: Apache-2.0
@@ -0,0 +1,78 @@
1
+ # Files of application_sdk/ shipped in atlan-application-sdk-api (paths from the repo root).
2
+ # GENERATED by .github/scripts/gen_api_files.py from [tool.atlan-api.seeds] in
3
+ # packages/api/pyproject.toml — do not edit; add a seed and regenerate.
4
+ application_sdk/__init__.py
5
+ application_sdk/_build_info.py
6
+ application_sdk/_context_errors.py
7
+ application_sdk/_install.py
8
+ application_sdk/_logging.py
9
+ application_sdk/_runtime/__init__.py
10
+ application_sdk/_runtime/offload.py
11
+ application_sdk/_runtime/progress.py
12
+ application_sdk/clients/__init__.py
13
+ application_sdk/clients/_interface.py
14
+ application_sdk/clients/_sql_failure_classifier.py
15
+ application_sdk/clients/base.py
16
+ application_sdk/clients/http_errors.py
17
+ application_sdk/clients/models.py
18
+ application_sdk/clients/sql.py
19
+ application_sdk/clients/sql_errors.py
20
+ application_sdk/clients/sql_typecasters.py
21
+ application_sdk/clients/ssl_utils.py
22
+ application_sdk/common/__init__.py
23
+ application_sdk/common/_generated_tree.py
24
+ application_sdk/common/_listing.py
25
+ application_sdk/common/aws_utils.py
26
+ application_sdk/common/aws_utils_errors.py
27
+ application_sdk/common/build_identity.py
28
+ application_sdk/common/concurrency.py
29
+ application_sdk/common/errors.py
30
+ application_sdk/common/filter_matching.py
31
+ application_sdk/common/logger.py
32
+ application_sdk/common/models.py
33
+ application_sdk/common/sql_filters.py
34
+ application_sdk/common/sql_filters_errors.py
35
+ application_sdk/common/task_queue.py
36
+ application_sdk/common/types.py
37
+ application_sdk/common/utils.py
38
+ application_sdk/constants.py
39
+ application_sdk/contracts/__init__.py
40
+ application_sdk/contracts/base.py
41
+ application_sdk/contracts/events.py
42
+ application_sdk/contracts/types.py
43
+ application_sdk/contracts/types_errors.py
44
+ application_sdk/credentials/__init__.py
45
+ application_sdk/credentials/errors.py
46
+ application_sdk/credentials/extra.py
47
+ application_sdk/credentials/ingress.py
48
+ application_sdk/credentials/ref.py
49
+ application_sdk/credentials/spec.py
50
+ application_sdk/credentials/types.py
51
+ application_sdk/credentials/utils.py
52
+ application_sdk/errors/__init__.py
53
+ application_sdk/errors/base.py
54
+ application_sdk/errors/categories.py
55
+ application_sdk/errors/http.py
56
+ application_sdk/errors/leaves.py
57
+ application_sdk/errors/wire.py
58
+ application_sdk/handler/__init__.py
59
+ application_sdk/handler/_warmup.py
60
+ application_sdk/handler/asgi.py
61
+ application_sdk/handler/base.py
62
+ application_sdk/handler/context.py
63
+ application_sdk/handler/contracts.py
64
+ application_sdk/handler/manifest.py
65
+ application_sdk/handler/metadata_routes.py
66
+ application_sdk/handler/object_routes.py
67
+ application_sdk/handler/request_contract.py
68
+ application_sdk/handler/routes.py
69
+ application_sdk/handler/service_errors.py
70
+ application_sdk/server/__init__.py
71
+ application_sdk/server/fastapi/models.py
72
+ application_sdk/templates/__init__.py
73
+ application_sdk/templates/contracts/__init__.py
74
+ application_sdk/templates/contracts/base_metadata_extraction.py
75
+ application_sdk/templates/contracts/incremental_sql.py
76
+ application_sdk/templates/contracts/sql_metadata.py
77
+ application_sdk/templates/contracts/sql_query.py
78
+ application_sdk/version.py