| Name | py-sarvcrm-api JSON |
| Version |
0.1.3
JSON |
| download |
| home_page | https://github.com/Radin-System/py-sarvcrm-api |
| Summary | Simple sarvcrm api module |
| upload_time | 2025-01-05 09:22:56 |
| maintainer | None |
| docs_url | None |
| author | Radin-System |
| requires_python | >=3.11 |
| license | MIT License Copyright (c) 2024 Radin-System Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "py-sarvcrm-api"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
python
library
sarvcrm
hamkaransystem
api
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# SarvClient API Interaction Module
## Overview
The **SarvClient** module provides a Python interface for interacting with the SarvCRM API. It simplifies authentication, CRUD operations, and module-specific functionalities for seamless integration with SarvCRM.
[SarvCRM API Documents](https://app.sarvcrm.com/webservice/)
## Features
- **Authentication**: Log in and manage sessions with the SarvCRM API.
- **CRUD Operations**: Perform Create, Read, Update, and Delete transactions via simple methods.
- **Context Manager Support**: Automatically handle login and logout within `with` statements.
- **Localization**: Supports specifying the desired language for API interactions.
- **Utility Methods**: Format dates, times, and other helper functionalities compliant with SarvCRM standards.
---
## Installation
1. Ensure you have Python 3.11+ installed.
2. Make Sure pip and git are installed
3. Install the package
```bash
pip install py-sarvcrm-api
```
---
## Quick Start
### Example Usage
```python
from sarvcrm_api import SarvClient, SarvURL
# SarvURL = 'https://app.sarvcrm.com/API.php'
# Initialize the client
client = SarvClient(
base_url=SarvURL, # you can specify your own url if you have local server
utype="youre_instance_utype",
username="your_username",
password="your_password",
language="en_US"
)
# Use as a context manager for clean execution
print(f'Connecting to {SarvURL}')
with client:
# Create new item in Accounts
uid = client.Accounts.create(type='Corporate', name='RadinSystem', numbers=['02145885000'])
print(f'New Account Created: {uid}')
# Read one item record
record = clinet.Accounts.read_record(uid)
print(f'Single Account record: {record}')
# Read List of items
records = client.Accounts.read_list(order_by='name')
print('Accounts list:')
for account in Accounts:
print(f' - {account}')
# Update an item
updated_item = client.Accounts.update(uid, name='Radin-System')
print(f'Updated item id: {updated_item}')
# Search for data by phone number
result = client.search_by_number(number="02145885000", module=client.Accounts) # module is optional
print(f'Search by number result: {result}')
# Delete Item
deleted_item = client.Accounts.delete(uid)
print(f'Deleted item: {deleted_item}')
```
---
## Class Details
### `SarvClient`
#### Constructor
```python
SarvClient(
base_url: str,
utype: str,
username: str,
password: str,
login_type: Optional[str] = None, # eg. 'portal' for portal users
language: str = "en_US", # Options: fa_IR, en_US
is_password_md5: bool = False
)
```
**Parameters**:
- `base_url`: The base URL for the SarvCRM API.
- `utype`: Utype of your sarvcrm instance.
- `username`: Your SarvCRM username.
- `password`: Password for authentication.
- `login_type`: (Optional) Login type for advanced configurations.
- `language`: Language code (default: `en_US`).
- `is_password_md5`: Whether the password is already MD5-hashed.
---
### Methods
#### `iso_time_output`
Formats `datetime` or `timedelta` objects according to SarvCRM standards.
#### `login`
Authenticates the user and retrieves an access token.
#### `logout`
Clears the session token.
#### `search_by_number`
Searches a module or all modules for records matching a given phone number.
---
**Attributes**:
- `Accounts`, `AosContracts`, `AosInvoices`, `AosPdfTemplates`, etc.: Module instances for various SarvCRM functionalities.
**Description**:
Initializes all the modules as attributes of the `ModulesMixin` class for easy access.
---
### `SarvModule`
#### Constructor
```python
SarvModule(_client: SarvClient)
```
**Attributes**:
- `_module_name`: The name of the module.
- `_label_en`: The label of the module in English.
- `_label_pr`: The label of the module in Persian.
- `_client`: The `SarvClient` instance for API interactions.
#### Methods
- `create(**KWArgs) -> str`
Creates a new record in the module.
- `read_list(query: Optional[str] = None, order_by: Optional[str] = None, select_fields: Optional[list[str]] = None, limit: int = None, offset: int = None) -> list`
Retrieves a list of items from the module.
- `real_list_all(query: Optional[str] = None, order_by: Optional[str] = None, select_fields: Optional[list[str]] = None, item_buffer: int = 300) -> list`
Retrieves all items as a list from the module.
- `read_record(pk: str) -> dict`
Fetches a single record by ID.
- `update(pk: str, **fields_data) -> str`
Updates an existing record.
- `delete(pk: str) -> str | None`
Deletes a record by ID.
- `get_module_fields() -> dict[str, dict]`
Retrieves the fields of the module.
- `get_relationships(related_field: str, query: Optional[str] = None, order_by: Optional[str] = None, select_fields: Optional[list[str]] = None, limit: int = None, offset: int = None) -> list`
Fetches related items.
- `save_relationships(pk: str, field_name: str, related_records: list) -> list`
Saves relationships between records.
---
## Additional Features
- **Error Handling**: Raise `SarvException` for API errors.
- **Secure Defaults**: Passwords are hashed with MD5 unless explicitly provided as pre-hashed.
---
## License
This module is licensed for Radin System. For details, see the [LICENSE](LICENSE) file.
Raw data
{
"_id": null,
"home_page": "https://github.com/Radin-System/py-sarvcrm-api",
"name": "py-sarvcrm-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "python, library, sarvcrm, hamkaransystem, api",
"author": "Radin-System",
"author_email": "Radin-System <technical@rsto.ir>",
"download_url": "https://files.pythonhosted.org/packages/00/24/3494ecd07f988c453fd77361fa8de9d1a4ce517c9b26776a50d8d9211e64/py_sarvcrm_api-0.1.3.tar.gz",
"platform": null,
"description": "# SarvClient API Interaction Module\n\n## Overview\n\nThe **SarvClient** module provides a Python interface for interacting with the SarvCRM API. It simplifies authentication, CRUD operations, and module-specific functionalities for seamless integration with SarvCRM.\n\n[SarvCRM API Documents](https://app.sarvcrm.com/webservice/)\n\n## Features\n- **Authentication**: Log in and manage sessions with the SarvCRM API.\n- **CRUD Operations**: Perform Create, Read, Update, and Delete transactions via simple methods.\n- **Context Manager Support**: Automatically handle login and logout within `with` statements.\n- **Localization**: Supports specifying the desired language for API interactions.\n- **Utility Methods**: Format dates, times, and other helper functionalities compliant with SarvCRM standards.\n\n---\n\n## Installation\n\n1. Ensure you have Python 3.11+ installed.\n2. Make Sure pip and git are installed\n3. Install the package\n ```bash\n pip install py-sarvcrm-api\n ```\n\n---\n\n## Quick Start\n\n### Example Usage\n\n```python\nfrom sarvcrm_api import SarvClient, SarvURL\n\n# SarvURL = 'https://app.sarvcrm.com/API.php'\n\n# Initialize the client\nclient = SarvClient(\n base_url=SarvURL, # you can specify your own url if you have local server\n utype=\"youre_instance_utype\",\n username=\"your_username\",\n password=\"your_password\",\n language=\"en_US\"\n)\n\n# Use as a context manager for clean execution\nprint(f'Connecting to {SarvURL}')\nwith client:\n # Create new item in Accounts\n uid = client.Accounts.create(type='Corporate', name='RadinSystem', numbers=['02145885000'])\n print(f'New Account Created: {uid}')\n \n # Read one item record\n record = clinet.Accounts.read_record(uid)\n print(f'Single Account record: {record}')\n\n # Read List of items\n records = client.Accounts.read_list(order_by='name')\n print('Accounts list:')\n for account in Accounts:\n print(f' - {account}')\n\n # Update an item\n updated_item = client.Accounts.update(uid, name='Radin-System')\n print(f'Updated item id: {updated_item}')\n\n # Search for data by phone number\n result = client.search_by_number(number=\"02145885000\", module=client.Accounts) # module is optional\n print(f'Search by number result: {result}')\n\n # Delete Item\n deleted_item = client.Accounts.delete(uid)\n print(f'Deleted item: {deleted_item}')\n\n```\n\n---\n\n## Class Details\n\n### `SarvClient`\n\n#### Constructor\n```python\nSarvClient(\n base_url: str,\n utype: str,\n username: str,\n password: str,\n login_type: Optional[str] = None, # eg. 'portal' for portal users\n language: str = \"en_US\", # Options: fa_IR, en_US\n is_password_md5: bool = False\n)\n```\n\n**Parameters**:\n- `base_url`: The base URL for the SarvCRM API.\n- `utype`: Utype of your sarvcrm instance.\n- `username`: Your SarvCRM username.\n- `password`: Password for authentication.\n- `login_type`: (Optional) Login type for advanced configurations.\n- `language`: Language code (default: `en_US`).\n- `is_password_md5`: Whether the password is already MD5-hashed.\n\n---\n\n### Methods\n\n#### `iso_time_output`\nFormats `datetime` or `timedelta` objects according to SarvCRM standards.\n\n#### `login`\nAuthenticates the user and retrieves an access token.\n\n#### `logout`\nClears the session token.\n\n#### `search_by_number`\nSearches a module or all modules for records matching a given phone number.\n\n---\n\n**Attributes**:\n- `Accounts`, `AosContracts`, `AosInvoices`, `AosPdfTemplates`, etc.: Module instances for various SarvCRM functionalities.\n\n**Description**:\nInitializes all the modules as attributes of the `ModulesMixin` class for easy access.\n\n---\n\n### `SarvModule`\n\n#### Constructor\n```python\nSarvModule(_client: SarvClient)\n```\n\n**Attributes**:\n- `_module_name`: The name of the module.\n- `_label_en`: The label of the module in English.\n- `_label_pr`: The label of the module in Persian.\n- `_client`: The `SarvClient` instance for API interactions.\n\n#### Methods\n\n- `create(**KWArgs) -> str`\n Creates a new record in the module.\n\n- `read_list(query: Optional[str] = None, order_by: Optional[str] = None, select_fields: Optional[list[str]] = None, limit: int = None, offset: int = None) -> list`\n Retrieves a list of items from the module.\n\n- `real_list_all(query: Optional[str] = None, order_by: Optional[str] = None, select_fields: Optional[list[str]] = None, item_buffer: int = 300) -> list`\n Retrieves all items as a list from the module.\n\n- `read_record(pk: str) -> dict`\n Fetches a single record by ID.\n\n- `update(pk: str, **fields_data) -> str`\n Updates an existing record.\n\n- `delete(pk: str) -> str | None`\n Deletes a record by ID.\n\n- `get_module_fields() -> dict[str, dict]`\n Retrieves the fields of the module.\n\n- `get_relationships(related_field: str, query: Optional[str] = None, order_by: Optional[str] = None, select_fields: Optional[list[str]] = None, limit: int = None, offset: int = None) -> list`\n Fetches related items.\n\n- `save_relationships(pk: str, field_name: str, related_records: list) -> list`\n Saves relationships between records.\n\n---\n\n## Additional Features\n\n- **Error Handling**: Raise `SarvException` for API errors.\n- **Secure Defaults**: Passwords are hashed with MD5 unless explicitly provided as pre-hashed.\n\n---\n\n## License\n\nThis module is licensed for Radin System. For details, see the [LICENSE](LICENSE) file.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 Radin-System Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"py-sarvcrm-api\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Simple sarvcrm api module",
"version": "0.1.3",
"project_urls": {
"BugTracker": "https://github.com/Radin-System/py-sarvcrm-api/issues",
"Homepage": "https://github.com/Radin-System/py-sarvcrm-api"
},
"split_keywords": [
"python",
" library",
" sarvcrm",
" hamkaransystem",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "df8debd9964cb96f4bfc5044c521f4b723c4ffec53af51653ff18b465b09b932",
"md5": "f34b94cb0997175f834ce44e2179cb80",
"sha256": "ab48a8d32da0c4ac0319a2a038e4d68bd65f23d74eef0475613294c438f0fd3b"
},
"downloads": -1,
"filename": "py_sarvcrm_api-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f34b94cb0997175f834ce44e2179cb80",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 24852,
"upload_time": "2025-01-05T09:22:54",
"upload_time_iso_8601": "2025-01-05T09:22:54.940032Z",
"url": "https://files.pythonhosted.org/packages/df/8d/ebd9964cb96f4bfc5044c521f4b723c4ffec53af51653ff18b465b09b932/py_sarvcrm_api-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "00243494ecd07f988c453fd77361fa8de9d1a4ce517c9b26776a50d8d9211e64",
"md5": "04c35fee4ef0b894a16364db61ddf7a2",
"sha256": "2280a755a14fcca975a920e68f107344df7b66e58adfc6f13795dc0940d3caec"
},
"downloads": -1,
"filename": "py_sarvcrm_api-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "04c35fee4ef0b894a16364db61ddf7a2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 13750,
"upload_time": "2025-01-05T09:22:56",
"upload_time_iso_8601": "2025-01-05T09:22:56.490737Z",
"url": "https://files.pythonhosted.org/packages/00/24/3494ecd07f988c453fd77361fa8de9d1a4ce517c9b26776a50d8d9211e64/py_sarvcrm_api-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-05 09:22:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Radin-System",
"github_project": "py-sarvcrm-api",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "py-sarvcrm-api"
}
