Skip to main content

A wrapper for the PrivateBin API

Project description

Codacy Badge codecov Build Status Maintainability Code Climate issues Code Climate technical debt GitHub repo size GitHub

PrivateBin API is a wrapper for API interactions with PrivateBin instances. It allows you to send, get, and delete pastes from PrivateBin instances.

Installing PrivateBin API and Supported Versions

PrivateBin API is available on PyPI: (not quite yet)

$ python -m pip install privatebinapi

PrivateBin API officially supports Python 3.6+.

Features

  • Send, retrieve, and delete pastes on any PrivateBin instance

  • Officially supports PrivateBin 1.0 through 1.3

  • Full support for both synchronous and asynchronous code

  • Upload and download files

  • Proxy support

Examples

Basic usage

PrivateBin API is designed to be as easy to use as possible. A quick example of the most basic features is shown below:

>>> import privatebinapi
>>> send_response = privatebinapi.send("https://vim.cx", text="Hello, world!")
>>> get_response = privatebinapi.get(send_response["full_url"])
>>> get_response['text'] == "Hello, world!"
True
>>> delete_response = privatebinapi.delete(send_response["full_url"], send_response["deletetoken"])

Each function returns a modified version of the JSON received from the PrivateBin instance.

All parameters shown in the docs below are optional and may be combined in any way.

Sending a Paste

To send a paste containing nothing but text, do the following:

>>> import privatebinapi
>>> response = privatebinapi.send("https://vim.cx", text="Hello, world!")

You can expect the send function to return something similar to the following:

{
    "deletetoken": "< paste delete token >",
    "full_url": "< direct link to paste> ",
    "id": "< paste ID >",
    "passcode": "< paste passcode >",
    "status": 0,
    "url": "/?< paste ID >"
}

Setting an Expiration

There are a limited number of valid expiration times. You must select one of the following:

("5min", "10min", "1hour", "1day", "1week", "1month", "1year", "never")

The default is "1day".

>>> import privatebinapi
>>> response = privatebinapi.send(
...     "https://vim.cx",
...     text="Hello, world!",
...     expiration="5min"
... )

Setting a password

Putting a password on your paste is easy:

>>> import privatebinapi
>>> response = privatebinapi.send(
...     "https://vim.cx",
...     text="Hello, world!",
...     password="Secure123!"
... )

Choosing Compression

There are only two valid options for this parameter: "zlib" and None. The default is "zlib".

>>> import privatebinapi
>>> response = privatebinapi.send(
...     "https://vim.cx",
...     text="Hello, world!",
...     compression=None
... )

Choosing a Format

There are only three valid options for this parameter: "plaintext", "syntaxhighlighting", and "markdown". The default is "plaintext".

>>> import privatebinapi
>>> response = privatebinapi.send(
...     "https://vim.cx",
...     text="Hello, world!",
...     formatting="markdown"
... )

Burn After Reading

If you want a paste to be deleted immediately after being read, pass True to the burn_after_reading parameter. The default is False.

>>> import privatebinapi
>>> response = privatebinapi.send(
...     "https://vim.cx",
...     text="Hello, world!",
...     burn_after_reading=True
... )

Enable Discussion

To enable discussion, pass True to the discussion parameter. The default is False.

>>> import privatebinapi
>>> response = privatebinapi.send(
...     "https://vim.cx",
...     text="Hello, world!",
...     discussion=True
... )

Getting a Paste

Getting a paste from a PrivateBin instance is very easy:

>>> import privatebinapi
>>> response = privatebinapi.get("https://example.com/?fakePasteLink#1234567890")

You can expect the get function to return something similar to the following:

{
    "attachment": {
        "content": b"< attachment content in bytes >",
        "filename": "< name of attachment >"
    },
    "id": '< paste ID >",
    "meta": {
        "created": < UNIX timestamp >,
        "time_to_live": < seconds until deletion >
    },
    "status": 0,
    "text": "< text content of the paste >",
    "url": "/?< paste ID >",
    "v": < encryption version 1 or 2 >}
}

Getting a Password Protected Paste

If the paste is password protected, use the password parameter.

>>> import privatebinapi
>>> response = privatebinapi.get(
...     "https://example.com/?fakePasteLink#1234567890",
...     password="Secure123!"
... )

Deleting a Paste

You can expect the delete function to return something similar to the following:

{
    "id": '< paste ID >",
    "status": 0,
    "url": "/?< paste ID >",
}

To delete a paste, you need its URL and delete token.

>>> import privatebinapi
>>> response = privatebinapi.delete(
...     "https://example.com/?fakePasteLink#1234567890",
...     "fake1delete2token3"
... )

Using a Proxy

All functions have an optional keyword parameter, proxies, that accepts a dictionary of proxies like you would see in the Requests package.

>>> import privatebinapi
>>> response = privatebinapi.send(
...     "https://vim.cx",
...     text="Hello, world!",
...     proxies={
...         "http": "http://example.com/proxy:80",
...         "https": "https://example.com/proxy:8080"
...     }
... )

Using Async Functions

privatebinapi.send, privatebinapi.get and privatebinapi.delete all have async analogs. They accept all the same parameters that their synchronous counterparts do.

import asyncio

import privatebinapi

async def main():
    send_response = await privatebinapi.send_async(
        "https://vim.cx",
        text="Hello, world!"
    )
    get_response = await privatebinapi.get_async(send_response["full_url"])
    delete_response = await privatebinapi.delete_async(
        send_response["full_url"],
        send_response["deletetoken"]
    )

loop = asyncio.get_event_loop()
loop.run_until_complete(main())

Both privatebinapi.send and privatebinapi.get do encryption and decryption using an executor. It will use the default executor for your event loop if executor is None.

License

PrivateBin API is offered under the MIT license.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

PrivateBinAPI-1.0.0.tar.gz (8.7 kB view details)

Uploaded Source

Built Distribution

PrivateBinAPI-1.0.0-py3-none-any.whl (10.9 kB view details)

Uploaded Python 3

File details

Details for the file PrivateBinAPI-1.0.0.tar.gz.

File metadata

  • Download URL: PrivateBinAPI-1.0.0.tar.gz
  • Upload date:
  • Size: 8.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/51.1.0.post20201221 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.8.1

File hashes

Hashes for PrivateBinAPI-1.0.0.tar.gz
Algorithm Hash digest
SHA256 2a19cff9980dd09fb079f73fba1644bca6756c7ca4911fce9b822130069cc036
MD5 886f4eaf3f009a55476dd02bde42a9b5
BLAKE2b-256 711f12af0fc9934b4d62fd5ba26c505aa4cceb03437841b7cdc7bad84d186be6

See more details on using hashes here.

File details

Details for the file PrivateBinAPI-1.0.0-py3-none-any.whl.

File metadata

  • Download URL: PrivateBinAPI-1.0.0-py3-none-any.whl
  • Upload date:
  • Size: 10.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/51.1.0.post20201221 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.8.1

File hashes

Hashes for PrivateBinAPI-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 a894bb124a0eb280749051a2e8b84a69786dc9f54207b845dc56194cdf226817
MD5 9dc7b56892b02ea76528c6dfa772b7b2
BLAKE2b-256 30099dd88eab2a35b12d255d9f0d77b54089c53a74e55a3d1fa168a3a05a1c1f

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page