Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Unified README added #16

Merged
merged 4 commits into from
Feb 2, 2024
Merged

Unified README added #16

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2b2d45a
feat(README): unified README added
650elx Jan 26, 2024
41bc8f4
fix(style): naming consistency fixed
650elx Jan 29, 2024
0a5f6d1
feat(README): restore some of the content
650elx Feb 1, 2024
972f68f
feat(README): make README left aligned
650elx Feb 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 39 additions & 82 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,29 @@
<h1 align="center">
# Sinch Python SDK

[![Sinch Logo](https://developers.sinch.com/static/logo-07afe977d6d9dcd21b066d1612978e5c.svg)](https://www.sinch.com)
Here you'll find documentation related to the Sinch Python SDK, including how to install it, initialize it, and start developing Python code using Sinch services.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BTW, I saw in design guide that our logo is left align

Copy link
Collaborator Author

@650elx 650elx Feb 1, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've tried it but it looks mediocre IMO. I prefer to keep this as "center"


Python SDK
To use Sinch services, you'll need a Sinch account and access keys. You can sign up for an account and create access keys at [dashboard.sinch.com](https://dashboard.sinch.com).

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/sinch/sinch-sdk-python/blob/main/LICENSE)


[![Python 3.9](https://img.shields.io/badge/python-3.9-blue.svg)](https://www.python.org/downloads/release/python-390/)
[![Python 3.10](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/release/python-3100/)
[![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/release/python-3110/)
[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/release/python-3120/)

Copy link

@Dovchik Dovchik Jan 30, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's nice to have such a fluff and personal touch in the repo so it's not worth removing in my opinion

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm happy to bring this stuff back :)


</h1>

## Welcome to Sinch's Python SDK.

Here you'll find documentation to start developing Python code using Sinch services.

To use this SDK you'll need a Sinch account and API keys. Please sign up at [sinch.com](https://sinch.com)

For more in depth version of the Sinch APIs, please refer to the official developer portal - [developers.sinch.com](https://developers.sinch.com/)
For more information on the Sinch APIs on which this SDK is based, refer to the official [developer documentation portal](developers.sinch.com).

**This SDK is currently available to selected developers for preview use only. It is being provided for the purpose of collecting feedback, and should not be used in production environments.**

* [Installation](#installation)
* [Getting started](#getting-started)
* [Logging](#logging)
* [Custom HTTP client implementation](#custom-http-client-implementation)
***
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Getting started](#getting-started)
- [Logging]()

## Prerequisites

- Python in one of the supported versions - 3.9, 3.10, 3.11, 3.12
- pip
- Sinch account

## Installation

You can install this package to your virtual environment or to your global Python installation by cloning this repo and typing:
You can install this package by typing:
`pip install sinch`


## Getting started

### Client initialization
Expand All @@ -52,7 +38,9 @@ from sinch import Client
sinch_client = Client(
key_id="key_id",
key_secret="key_secret",
project_id="some_project"
project_id="some_project",
application_key="application_key",
application_secret="application_secret"
)
```

Expand All @@ -63,33 +51,33 @@ from sinch import Client
sinch_client = Client(
key_id=os.getenv("KEY_ID"),
key_secret=os.getenv("KEY_SECRET"),
project_id=os.getenv("PROJECT_ID")
project_id=os.getenv("PROJECT_ID"),
application_key=os.getenv("APPLICATION_KEY"),
application_secret=os.getenv("APPLICATION_SECRET")
)
```

## Products

### Domains
Sinch client provides access to the following Sinch products:
- Numbers
- SMS
- Verification
- Conversation API
- Additional products coming soon!

Each product from Sinch portfolio is considered and coded as a separate `domain`.
Domain contains data structures specific to that service, that can be also used by the developer.
## Logging

Abstract directory structure of the `domain`:
```
├── domain_name
│ ├── __init__.py (public interface of the domain)
│ ├── endpoints (directory with endpoint definitions)
│ ├── models (direcotry with data models definitions)
│ ├── enums.py (enums that can be helpful for a developer; e.g. SinchNumberType)
│ ├── exceptions.py (exceptions spefific for a particular domain; e.g. NumbersException)
│
```
Logging configuration for this SDK utilizes following hierarchy:
1. If no configuration was provided via `logger_name` or `logger` configurable, SDK will inherit configuration from the root logger with the `Sinch` prefix.
2. If `logger_name` configurable was provided, SDK will use logger related to that name. For example: `myapp.sinch` will inherit configuration from the `myapp` logger.
3. If `logger` (logger instance) configurable was provided, SDK will use that particular logger for all its logging operations.

Sinch client provides access to the following Sinch product domains:
If all logging returned by this SDK needs to be disabled, usage of `NullHanlder` provided by the standard `logging` module is advised.

- Numbers
- Conversation API
- SMS


## Sample apps

Usage example of the `numbers` domain:

Expand All @@ -116,9 +104,9 @@ ListAvailableNumbersResponse(

### Handling exceptions

Each domain throws a `DomainException` exception for an unsuccessful backed call.
Each API throws a custom, API related exception for an unsuccessful backed call.

Example for Numbers Domain:
Example for Numbers API:

```python
from sinch.domains.numbers.exceptions import NumbersException
Expand All @@ -134,37 +122,6 @@ except NumbersException as err:

For handling all possible exceptions thrown by this SDK use `SinchException` (superclass of all Sinch exceptions) form `sinch.core.exceptions`.

## License

## Logging

Logging configuration for this SDK utilizes following hierarchy:
1. If no configuration was provided via `logger_name` or `logger` configurable, SDK will inherit configuration from the root logger with the `Sinch` prefix.
2. If `logger_name` configurable was provided, SDK will use logger related to that name. For example: `myapp.sinch` will inherit configuration from the `myapp` logger.
3. If `logger` (logger instance) configurable was provided, SDK will use that particular logger for all its logging operations.

If all logging returned by this SDK needs to be disabled, usage of `NullHanlder` provided by the standard `logging` module is advised.


## Custom HTTP client implementation

By default, two HTTP implementations are provided:
- Synchronous using `requests` HTTP library
- Asynchronous using `aiohttp` HTTP library

For creating custom HTTP client code, use either `Client` or `ClientAsync` client and inject your transport during initialisation:
```python
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's nice to have example, maybe you can keep them?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

sinch_client = ClientAsync(
key_id="Spanish",
key_secret="Inquisition",
project_id="some_project",
transport=MyHTTPAsyncImplementation
)
```

Custom client has to obey types and methods described by `HTTPTransport` abstract base class:
```python
class HTTPTransport(ABC):
@abstractmethod
def request(self, endpoint: HTTPEndpoint) -> HTTPResponse:
pass
```
This project is licensed under the Apache License. See the [LICENSE](license.md) file for the license text.
Loading