==============
PrivateBin Request forked from PrivateBin Request
==============

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

Added the ability to adjust http headers that request to PrivateBin instances.

(Should have the same content as PrivateBin API README.md)
PrivateBin Request is a wrapper for API interactions with PrivateBin instances.
It allows you to send, get, and delete pastes from PrivateBin instances.


default headers:

.. code:: python
   {
      'X-Requested-With': 'JSONHttpRequest', 
      'User-Agent': 'PrivateBinRequest/1.0.0'
   }

You can adjust the headers by passing a dictionary to the `headers` parameter in the `send`, `get`, and `delete` functions.

.. code:: python
   
   import pbrequest
   pbrequest.set_headers({
      'Content-type': 'application/x-www-form-urlencoded; charset=UTF-8', 
      'User-Agent': 'Mozilla/5.0',
      'Custom-Header': 'Custom-Value'
   })

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

   print(response)

Installing PrivateBin Request and Supported Versions
------------------------------------------------

PrivateBin Request is available on PyPI:

.. code:: console

   $ python -m pip install pbrequest

PrivateBin Request 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 Request is designed to be as easy to use as possible. A quick
example of the most basic features is shown below:

.. code:: python

   >>> import pbrequest
   >>> send_response = pbrequest.send("https://vim.cx", text="Hello, world!")
   >>> get_response = pbrequest.get(send_response["full_url"])
   >>> get_response['text'] == "Hello, world!"
   True
   >>> delete_response = pbrequest.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:

.. code:: python

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

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

.. code:: text

   {
       "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:

.. code:: python

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

The default is ``"1day"``.

.. code:: python

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

Setting a password
^^^^^^^^^^^^^^^^^^

Putting a password on your paste is easy:

.. code:: python

   >>> import pbrequest
   >>> response = pbrequest.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"``.

.. code:: python

   >>> import pbrequest
   >>> response = pbrequest.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"``.

.. code:: python

   >>> import pbrequest
   >>> response = pbrequest.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``.

.. code:: python

   >>> import pbrequest
   >>> response = pbrequest.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``.

.. code:: python

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

Getting a Paste
~~~~~~~~~~~~~~~

Getting a paste from a PrivateBin instance is very easy:

.. code:: python

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

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

.. code:: text

   {
       "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.

.. code:: python

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

Deleting a Paste
~~~~~~~~~~~~~~~~

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

.. code:: text

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

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

.. code:: python

   >>> import pbrequest
   >>> response = pbrequest.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.

.. code:: python

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

Using Async Functions
~~~~~~~~~~~~~~~~~~~~~

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

.. code:: python

   import asyncio

   import pbrequest

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

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

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

.. _executor: https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.Executor

License
~~~~~~~
PrivateBin Request is offered under the `MIT license`_.

.. _MIT license: https://github.com/Pioverpie/privatebin-api/blob/master/LICENSE


.. |Codacy Badge| image:: https://app.codacy.com/project/badge/Grade/b0b11fa99727453eb219bcd0b03f5868
   :target: https://www.codacy.com/gh/Pioverpie/privatebin-api/dashboard
.. |codecov| image:: https://codecov.io/gh/Pioverpie/privatebin-api/branch/master/graph/badge.svg?token=5YE0802BC1
   :target: https://codecov.io/gh/Pioverpie/privatebin-api
.. |Build Status| image:: https://travis-ci.org/Pioverpie/privatebin-api.svg?branch=master
   :target: https://travis-ci.org/Pioverpie/privatebin-api
.. |Maintainability| image:: https://api.codeclimate.com/v1/badges/b6dcd84fe476440a1811/maintainability
   :target: https://codeclimate.com/github/Pioverpie/privatebin-api/maintainability
.. |Code Climate issues| image:: https://img.shields.io/codeclimate/issues/Pioverpie/privatebin-api
   :target: https://codeclimate.com/github/Pioverpie/privatebin-api/issues
.. |Code Climate technical debt| image:: https://img.shields.io/codeclimate/tech-debt/Pioverpie/privatebin-api
   :target: https://codeclimate.com/github/Pioverpie/privatebin-api/trends/technical_debt
.. |GitHub repo size| image:: https://img.shields.io/github/repo-size/Pioverpie/privatebin-api
   :target: https://github.com/Pioverpie/privatebin-api
.. |License badge| image:: https://img.shields.io/github/license/Pioverpie/privatebin-api
   :alt: GitHub
   :target: https://github.com/Pioverpie/privatebin-api/blob/master/LICENSE
