mergepythonclient 0.0.1__tar.gz

mergepythonclient-0.0.1/LICENSE.md

@@ -0,0 +1,16 @@
+_Last updated: April 21, 2022_
+
+**Merge SDK & Code Snippets License**
+
+Merge makes available to Customers various software development kits ("**SDKs**") and code snippets ("**Snippets**") (together, the "**Merge Assets**") to assist with Merge Integrations and making connections to their Customer Application. Merge Assets are deemed Software under the MSA (defined below). All terms applicable to Software under the MSA apply with equal force and effect to the Merge Assets under this Merge SDK and Code Snippets License ("**License**").
+
+"**Customer**" means a person or entity that uses any of the Merge Assets. By using any Merge Asset, Customer agrees to the terms of this License.
+
+"**MSA**" for the purpose of this License means: (a) for Merge "Launch" Customers, the Subscriber Agreement (available at: [https://merge.dev/subscriber-agreement](https://merge.dev/subscriber-agreement)); and (b) for Merge "Growth" and/or "Expand" Customers, Merge's Master Services Agreement (available at [https://merge.dev/msa](https://merge.dev/msa)), unless Merge and Customer have entered into a separate written agreement governing the Customer's use of the Service. Customer's use of any Merge Asset will be governed by the applicable MSA as well as the additional terms of this License. Capitalized terms used but not defined herein shall have the meaning as set forth in the MSA. In the event of any inconsistency between the terms of the MSA and this License, the terms of the MSA will prevail.
+
+Merge reserves the right to modify or update this License in its sole discretion, the effective date of such updates and/or modifications will be the earlier of: (i) 30 days from the date of such update or modification; or (ii) Customer's continued use of any Merge Asset.
+
+1. **SDK and Snippets License**. Customer's right to access and use the Service under Section 1 of the MSA is extended to include use of the Merge Assets but solely during the Term and subject to the terms of the MSA.
+2. **Use with the Service Only**. Customer may use the Merge Assets but only in connections with the Service and Merge Integrations. Any other use of the Merge Assets requires Merge's prior written consent.
+3. **Limitations**. Customer's use of the Merge Assets may be subject to bandwidth limitations that Merge may impose from time to time during the Subscription. Merge will make commercially reasonable efforts to notify Customer of such limitations in advance via the location where Customer gained access to the applicable Merge Asset(s).
+4. **Merge Assets & Intellectual Property Rights**. Any modifications or derivatives (together, "**Asset Derivatives**") made by Customer to the Merge Assets are deemed "works made for hire" as that term is defined in the United States Copyright Act and are the sole property of Merge. To the extent that ownership of any Asset Derivative does not by operation of law vest in Merge, Customer hereby assigns to Merge all right, title and interest in and to the Asset Derivative, including all related intellectual property rights. Asset Derivatives will be governed by the terms of this License.

mergepythonclient-0.0.1/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.1
+Name: mergepythonclient
+Version: 0.0.1
+Summary: Client library for the merge API
+Home-page: https://github.com/merge-api/merge-python-client
+License: custom
+Author: Merge
+Author-email: hello@merge.dev
+Requires-Python: >=3.7,<4.0
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Dist: anyio (>=3.5.0)
+Requires-Dist: distro (>=1.7.0)
+Requires-Dist: httpx (>=0.23.0)
+Requires-Dist: pydantic (>=1.9.0)
+Requires-Dist: typing-extensions (>=4.1.1)
+Project-URL: Repository, https://github.com/merge-api/merge-python-client
+Description-Content-Type: text/markdown
+
+# Merge Python API Library
+
+[![PyPI version](https://img.shields.io/pypi/v/MergePythonClient.svg)](https://pypi.org/project/MergePythonClient/)
+
+The Merge Python library provides convenient access to the Merge REST API from any Python 3.7+
+application. It includes type definitions for all request params and response fields,
+and offers both synchronous and asynchronous clients powered by [httpx](https://github.com/encode/httpx).
+
+## Documentation
+
+The API documentation can be found [here](https://docs.merge.dev).
+
+## Installation
+
+```sh
+pip install MergePythonClient
+```
+
+## Usage
+
+```python
+from merge import Merge
+
+merge = Merge(
+    # defaults to os.environ.get("MERGE_API_KEY")
+    api_key="my api key",
+)
+
+account_detail = merge.hris.account_details.retrieve()
+```
+
+While you can provide an `api_key` keyword argument, we recommend using [python-dotenv](https://pypi.org/project/python-dotenv/)
+and adding `MERGE_API_KEY="my api key"` to your `.env` file so that your API Key is not stored in source control.
+
+## Async Usage
+
+Simply import `AsyncMerge` instead of `Merge` and use `await` with each API call:
+
+```python
+from merge import AsyncMerge
+
+merge = AsyncMerge(
+    # defaults to os.environ.get("MERGE_API_KEY")
+    api_key="my api key",
+)
+
+
+async def main():
+    account_detail = await merge.hris.account_details.retrieve()
+    print(account_detail)
+
+
+asyncio.run(main())
+```
+
+Functionality between the synchronous and asynchronous clients is otherwise identical.
+
+## Using Types
+
+Nested request parameters are [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict), while responses are [Pydantic](https://pydantic-docs.helpmanual.io/) models. This helps provide autocomplete and documentation within your editor.
+
+If you would like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `"basic"`.
+
+## Pagination
+
+List methods in the Merge API are paginated.
+
+This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
+
+```python
+import merge
+
+merge = Merge()
+
+all_sync_statuses = []
+# Automatically fetches more pages as needed.
+for sync_status in merge.hris.sync_status.list():
+    # Do something with sync_status here
+    all_sync_statuses.append(sync_status)
+print(all_sync_statuses)
+```
+
+Or, asynchronously:
+
+```python
+import asyncio
+import merge
+
+merge = AsyncMerge()
+
+
+async def main() -> None:
+    all_sync_statuses = []
+    # Iterate through items across all pages, issuing requests as needed.
+    async for sync_status in merge.hris.sync_status.list():
+        all_sync_statuses.append(sync_status)
+    print(all_sync_statuses)
+
+
+asyncio.run(main())
+```
+
+Alternatively, you can use the `.has_next_page()`, `.next_page_info()`, or `.get_next_page()` methods for more granular control working with pages:
+
+```python
+first_page = await merge.hris.sync_status.list()
+if first_page.has_next_page():
+    print(f"will fetch next page using these details: {first_page.next_page_info()}")
+    next_page = await first_page.get_next_page()
+    print(f"number of items we just fetched: {len(next_page.results)}")
+
+# Remove `await` for non-async usage.
+```
+
+Or just work directly with the returned data:
+
+```python
+first_page = await merge.hris.sync_status.list()
+
+print(f"next page cursor: {first_page.next}")  # => "next page cursor: ..."
+for sync_status in first_page.results:
+    print(sync_status.model_name)
+
+# Remove `await` for non-async usage.
+```
+
+## Nested params
+
+Nested parameters are dictionaries, typed using `TypedDict`, for example:
+
+```python
+from merge import Merge
+
+merge = Merge()
+
+merge.hris.account_details.retrieve(
+    params={},
+)
+```
+
+## Handling errors
+
+When the library is unable to connect to the API (e.g., due to network connection problems or a timeout), a subclass of `merge.APIConnectionError` is raised.
+
+When the API returns a non-success status code (i.e., 4xx or 5xx
+response), a subclass of `merge.APIStatusError` will be raised, containing `status_code` and `response` properties.
+
+All errors inherit from `merge.APIError`.
+
+```python
+from merge import Merge
+
+merge = Merge()
+
+try:
+    merge.hris.account_details.retrieve()
+except merge.APIConnectionError as e:
+    print("The server could not be reached")
+    print(e.__cause__)  # an underlying Exception, likely raised within httpx.
+except merge.RateLimitError as e:
+    print("A 429 status code was received; we should back off a bit.")
+except merge.APIStatusError as e:
+    print("Another non-200-range status code was received")
+    print(e.status_code)
+    print(e.response)
+```
+
+Error codes are as followed:
+
+| Status Code | Error Type                 |
+| ----------- | -------------------------- |
+| 400         | `BadRequestError`          |
+| 401         | `AuthenticationError`      |
+| 403         | `PermissionDeniedError`    |
+| 404         | `NotFoundError`            |
+| 422         | `UnprocessableEntityError` |
+| 429         | `RateLimitError`           |
+| >=500       | `InternalServerError`      |
+| N/A         | `APIConnectionError`       |
+
+### Retries
+
+Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
+Connection errors (for example, due to a network connectivity problem), 409 Conflict, 429 Rate Limit,
+and >=500 Internal errors will all be retried by default.
+
+You can use the `max_retries` option to configure or disable this:
+
+```python
+from merge import Merge
+
+# Configure the default for all requests:
+merge = Merge(
+    # default is 2
+    max_retries=0,
+)
+
+# Or, configure per-request:
+merge.with_options(max_retries=5).hris.account_details.retrieve()
+```
+
+### Timeouts
+
+Requests time out after 60 seconds by default. You can configure this with a `timeout` option,
+which accepts a float or an [`httpx.Timeout`](https://www.python-httpx.org/advanced/#fine-tuning-the-configuration):
+
+```python
+from merge import Merge
+
+# Configure the default for all requests:
+merge = Merge(
+    # default is 60s
+    timeout=20.0,
+)
+
+# More granular control:
+merge = Merge(
+    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
+)
+
+# Override per-request:
+merge.with_options(timeout=5 * 1000).hris.account_details.retrieve()
+```
+
+On timeout, an `APITimeoutError` is thrown.
+
+Note that requests which time out will be [retried twice by default](#retries).
+
+## Advanced: Configuring custom URLs, proxies, and transports
+
+You can configure the following keyword arguments when instantiating the client:
+
+```python
+import httpx
+from merge import Merge
+
+merge = Merge(
+    # Use a custom base URL
+    base_url="http://my.test.server.example.com:8083",
+    proxies="http://my.test.proxy.example.com",
+    transport=httpx.HTTPTransport(local_address="0.0.0.0"),
+)
+```
+
+See the httpx documentation for information about the [`proxies`](https://www.python-httpx.org/advanced/#http-proxying) and [`transport`](https://www.python-httpx.org/advanced/#custom-transports) keyword arguments.
+
+## Status
+
+This package is in beta. Its internals and interfaces are not stable and subject to change without a major semver bump;
+please reach out if you rely on any undocumented behavior.
+
+We are keen for your feedback; please email us at [hello@merge.dev](mailto:hello@merge.dev) or open an issue with questions,
+bugs, or suggestions.
+
+## Requirements
+
+Python 3.7 or higher.

mergepythonclient-0.0.1/README.md

@@ -0,0 +1,257 @@
+# Merge Python API Library
+
+[![PyPI version](https://img.shields.io/pypi/v/MergePythonClient.svg)](https://pypi.org/project/MergePythonClient/)
+
+The Merge Python library provides convenient access to the Merge REST API from any Python 3.7+
+application. It includes type definitions for all request params and response fields,
+and offers both synchronous and asynchronous clients powered by [httpx](https://github.com/encode/httpx).
+
+## Documentation
+
+The API documentation can be found [here](https://docs.merge.dev).
+
+## Installation
+
+```sh
+pip install MergePythonClient
+```
+
+## Usage
+
+```python
+from merge import Merge
+
+merge = Merge(
+    # defaults to os.environ.get("MERGE_API_KEY")
+    api_key="my api key",
+)
+
+account_detail = merge.hris.account_details.retrieve()
+```
+
+While you can provide an `api_key` keyword argument, we recommend using [python-dotenv](https://pypi.org/project/python-dotenv/)
+and adding `MERGE_API_KEY="my api key"` to your `.env` file so that your API Key is not stored in source control.
+
+## Async Usage
+
+Simply import `AsyncMerge` instead of `Merge` and use `await` with each API call:
+
+```python
+from merge import AsyncMerge
+
+merge = AsyncMerge(
+    # defaults to os.environ.get("MERGE_API_KEY")
+    api_key="my api key",
+)
+
+
+async def main():
+    account_detail = await merge.hris.account_details.retrieve()
+    print(account_detail)
+
+
+asyncio.run(main())
+```
+
+Functionality between the synchronous and asynchronous clients is otherwise identical.
+
+## Using Types
+
+Nested request parameters are [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict), while responses are [Pydantic](https://pydantic-docs.helpmanual.io/) models. This helps provide autocomplete and documentation within your editor.
+
+If you would like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `"basic"`.
+
+## Pagination
+
+List methods in the Merge API are paginated.
+
+This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
+
+```python
+import merge
+
+merge = Merge()
+
+all_sync_statuses = []
+# Automatically fetches more pages as needed.
+for sync_status in merge.hris.sync_status.list():
+    # Do something with sync_status here
+    all_sync_statuses.append(sync_status)
+print(all_sync_statuses)
+```
+
+Or, asynchronously:
+
+```python
+import asyncio
+import merge
+
+merge = AsyncMerge()
+
+
+async def main() -> None:
+    all_sync_statuses = []
+    # Iterate through items across all pages, issuing requests as needed.
+    async for sync_status in merge.hris.sync_status.list():
+        all_sync_statuses.append(sync_status)
+    print(all_sync_statuses)
+
+
+asyncio.run(main())
+```
+
+Alternatively, you can use the `.has_next_page()`, `.next_page_info()`, or `.get_next_page()` methods for more granular control working with pages:
+
+```python
+first_page = await merge.hris.sync_status.list()
+if first_page.has_next_page():
+    print(f"will fetch next page using these details: {first_page.next_page_info()}")
+    next_page = await first_page.get_next_page()
+    print(f"number of items we just fetched: {len(next_page.results)}")
+
+# Remove `await` for non-async usage.
+```
+
+Or just work directly with the returned data:
+
+```python
+first_page = await merge.hris.sync_status.list()
+
+print(f"next page cursor: {first_page.next}")  # => "next page cursor: ..."
+for sync_status in first_page.results:
+    print(sync_status.model_name)
+
+# Remove `await` for non-async usage.
+```
+
+## Nested params
+
+Nested parameters are dictionaries, typed using `TypedDict`, for example:
+
+```python
+from merge import Merge
+
+merge = Merge()
+
+merge.hris.account_details.retrieve(
+    params={},
+)
+```
+
+## Handling errors
+
+When the library is unable to connect to the API (e.g., due to network connection problems or a timeout), a subclass of `merge.APIConnectionError` is raised.
+
+When the API returns a non-success status code (i.e., 4xx or 5xx
+response), a subclass of `merge.APIStatusError` will be raised, containing `status_code` and `response` properties.
+
+All errors inherit from `merge.APIError`.
+
+```python
+from merge import Merge
+
+merge = Merge()
+
+try:
+    merge.hris.account_details.retrieve()
+except merge.APIConnectionError as e:
+    print("The server could not be reached")
+    print(e.__cause__)  # an underlying Exception, likely raised within httpx.
+except merge.RateLimitError as e:
+    print("A 429 status code was received; we should back off a bit.")
+except merge.APIStatusError as e:
+    print("Another non-200-range status code was received")
+    print(e.status_code)
+    print(e.response)
+```
+
+Error codes are as followed:
+
+| Status Code | Error Type                 |
+| ----------- | -------------------------- |
+| 400         | `BadRequestError`          |
+| 401         | `AuthenticationError`      |
+| 403         | `PermissionDeniedError`    |
+| 404         | `NotFoundError`            |
+| 422         | `UnprocessableEntityError` |
+| 429         | `RateLimitError`           |
+| >=500       | `InternalServerError`      |
+| N/A         | `APIConnectionError`       |
+
+### Retries
+
+Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
+Connection errors (for example, due to a network connectivity problem), 409 Conflict, 429 Rate Limit,
+and >=500 Internal errors will all be retried by default.
+
+You can use the `max_retries` option to configure or disable this:
+
+```python
+from merge import Merge
+
+# Configure the default for all requests:
+merge = Merge(
+    # default is 2
+    max_retries=0,
+)
+
+# Or, configure per-request:
+merge.with_options(max_retries=5).hris.account_details.retrieve()
+```
+
+### Timeouts
+
+Requests time out after 60 seconds by default. You can configure this with a `timeout` option,
+which accepts a float or an [`httpx.Timeout`](https://www.python-httpx.org/advanced/#fine-tuning-the-configuration):
+
+```python
+from merge import Merge
+
+# Configure the default for all requests:
+merge = Merge(
+    # default is 60s
+    timeout=20.0,
+)
+
+# More granular control:
+merge = Merge(
+    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
+)
+
+# Override per-request:
+merge.with_options(timeout=5 * 1000).hris.account_details.retrieve()
+```
+
+On timeout, an `APITimeoutError` is thrown.
+
+Note that requests which time out will be [retried twice by default](#retries).
+
+## Advanced: Configuring custom URLs, proxies, and transports
+
+You can configure the following keyword arguments when instantiating the client:
+
+```python
+import httpx
+from merge import Merge
+
+merge = Merge(
+    # Use a custom base URL
+    base_url="http://my.test.server.example.com:8083",
+    proxies="http://my.test.proxy.example.com",
+    transport=httpx.HTTPTransport(local_address="0.0.0.0"),
+)
+```
+
+See the httpx documentation for information about the [`proxies`](https://www.python-httpx.org/advanced/#http-proxying) and [`transport`](https://www.python-httpx.org/advanced/#custom-transports) keyword arguments.
+
+## Status
+
+This package is in beta. Its internals and interfaces are not stable and subject to change without a major semver bump;
+please reach out if you rely on any undocumented behavior.
+
+We are keen for your feedback; please email us at [hello@merge.dev](mailto:hello@merge.dev) or open an issue with questions,
+bugs, or suggestions.
+
+## Requirements
+
+Python 3.7 or higher.

mergepythonclient-0.0.1/pyproject.toml

@@ -0,0 +1,95 @@
+[tool.poetry]
+name = "MergePythonClient"
+version = "0.0.1"
+description = "Client library for the merge API"
+readme = "README.md"
+authors = ["Merge <hello@merge.dev>"]
+license = "custom"
+repository = "https://github.com/merge-api/merge-python-client"
+packages = [
+  { include = "merge", from = "src" }
+]
+
+[tool.poetry.dependencies]
+python = "^3.7"
+httpx = ">= 0.23.0"
+pydantic = ">= 1.9.0"
+typing-extensions = ">= 4.1.1"
+anyio = ">= 3.5.0"
+distro = ">= 1.7.0"
+
+
+[tool.poetry.group.dev.dependencies]
+pyright = "1.1.297"
+mypy = "1.1.1"
+black = "22.10.0"
+respx = "0.19.2"
+pytest = "7.1.1"
+pytest-asyncio = "0.18.3"
+ruff = "0.0.239"
+isort = "5.10.1"
+time-machine = "^2.9.0"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 120
+target-version = ["py37"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--tb=short"
+xfail_strict = true
+log_cli = true
+log_level = "INFO"
+asyncio_mode = "auto"
+filterwarnings = [
+  "error"
+]
+
+[tool.pyright]
+# this enables practically every flag given by pyright.
+# there are a couple of flags that are still disabled by
+# default in strict mode as they are experimental and niche.
+typeCheckingMode = "strict"
+pythonVersion = "3.7"
+
+exclude = [
+    "_dev",
+    ".venv"
+]
+reportImportCycles = false
+reportPrivateUsage = false
+
+[tool.isort]
+profile = "black"
+length_sort = true
+extra_standard_library = ["typing_extensions"]
+
+[tool.ruff]
+line-length = 120
+format = "grouped"
+target-version = "py37"
+select = [
+  # remove unused imports
+  "F401",
+  # bare except statements
+  "E722",
+  # print statements
+  "T201",
+  "T203",
+]
+unfixable = [
+  # disable auto fix for print statements
+  "T201",
+  "T203",
+]
+ignore-init-module-imports = true
+
+
+[tool.ruff.per-file-ignores]
+"bin/**.py" = ["T201", "T203"]
+"tests/**.py" = ["T201", "T203"]
+"examples/**.py" = ["T201", "T203"]