Metadata-Version: 2.5
Name: screenshotone
Version: 0.0.17
Summary: A Python SDK for ScreenshotOne.com API to take screenshots of URLs, render HTML as images and PDF
Project-URL: Homepage, https://screenshotone.com/
Project-URL: Docs, https://screenshotone.com/docs/getting-started/
Author-email: Dmytro Krasun <support@screenshotone.com>
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.7
Requires-Dist: requests>=2.28.1
Description-Content-Type: text/markdown

# pythonsdk

An official Python SDK for [ScreenshotOne.com API](https://screenshotone.com) to take screenshots of URLs, render HTML as images and PDF.

It takes minutes to start taking screenshots. Just [sign up](https://screenshotone.com/) to get access and secret keys, import the client, and you are ready to go.

See the [screenshot API options](https://screenshotone.com/docs/options/) for option descriptions and supported values.

Pass `access_key` to `Client` and use `.async_option(True)` for the API's `async` option. Repeated options such as `.proxy_bypass_hosts(["cdn.example.com", "cdn.*.screenshotone.com"])` accept lists.

## Installation

```shell
pip install screenshotone
```

## Usage

Generate a screenshot URL without executing the request. Or download the screenshot. It is up to you:

```python
import shutil
from screenshotone import Client, TakeOptions

# create API client
client = Client('<your access key>', '<your secret key>')

# set up options
options = (TakeOptions.url('https://screenshotone.com')
    .format("png")
    .viewport_width(1024)
    .viewport_height(768)
    .block_cookie_banners(True)
    .block_chats(True))

# generate the screenshot URL and share it with a user
url = client.generate_take_url(options)
# expected output: https://api.screenshotone.com/take?url=https%3A%2F%2Fscreenshotone.com&viewport_width=1024&viewport_height=768&block_cookie_banners=True&block_chats=True&access_key=<your access key>&signature=6afc9417a523788580fa01a9f668ea82c78a9d2b41441d2a696010bf2743170f

# or render a screenshot and download the image as stream
image = client.take(options)

# store the screenshot the example.png file
with open('example.png', 'wb') as result_file:
    shutil.copyfileobj(image, result_file)
```

### How to handle errors

Read about [how to handle the ScreenshotOne API errors](https://screenshotone.com/docs/guides/how-to-handle-api-errors/), and that's how you can get the HTTP status code and the error code of the request:

```python
from screenshotone import APIErrorException, InvalidRequestException

try:
    # ...
    # render a screenshot and download the image as stream
    image = client.take(options)
    # ...
except InvalidRequestException as e:
    print(f"Invalid request: {e}")
    if e.http_status_code:
        print(f"HTTP Status Code: {e.http_status_code}")
    if e.error_code:
        print(f"Error Code: {e.error_code}")
except APIErrorException as e:
    print(f"API Error: {e}")
    if e.http_status_code:
        print(f"HTTP Status Code: {e.http_status_code}")
    if e.error_code:
        print(f"Error Code: {e.error_code}")
except Exception as e:
    # handle any other exceptions
    print(f"An unexpected error occurred: {e}")
```

`InvalidRequestException` inherits from `APIErrorException`. Catch `APIErrorException` to handle both; place an `InvalidRequestException` handler first if you want to handle invalid requests separately.

## Development

Install the SDK and run the offline regression tests:

```shell
python -m pip install -e .
python -m unittest discover -s tests -v
```

The tests mock HTTP requests and do not require API keys or network access. `tests/fixtures/documented_options.json` contains a saved documentation snapshot and its verification date. These tests check the snapshot, not the live docs; refresh it when synchronizing the SDK with the docs.

CI runs the tests on pushes and pull requests using Python 3.7 through 3.14. The release workflow also runs the tests before publishing.

## Release

[Github Actions](https://github.com/screenshotone/pythonsdk/blob/main/.github/workflows/pypi-release.yml) is used to automate the release process and publishing to PyPI. Update the library version in `pyproject.toml` and [create a new release](https://github.com/screenshotone/pythonsdk/releases/new) to launch the `publish` workflow.

## Useful resources

Python tutorials from the ScreenshotOne blog:

- [Take website screenshots with Python](https://screenshotone.com/blog/how-to-take-website-screenshots-in-python/)
- [How to Take Bulk Screenshots in Python with a Screenshot API](https://screenshotone.com/blog/bulk-screenshots-python/)
- [How to Take Website Screenshots with Playwright in Python](https://screenshotone.com/blog/playwright-python-screenshots/)
- [How to Take Full Page Screenshots with Playwright in Python](https://screenshotone.com/blog/playwright-python-full-page-website-screenshots/)
- [How to Take Bulk Screenshots with Playwright in Python](https://screenshotone.com/blog/bulk-screenshots-playwright-python/)
- [Website Screenshots with Selenium in Python](https://screenshotone.com/blog/selenium-python-screenshots/)
- [How to Take Screenshots with pyppeteer in Python](https://screenshotone.com/blog/pyppeteer-python-screenshots/)

## License

`screenshotone/pythonsdk` is released under [the MIT license](LICENSE).
