Go to github [README.md](https://github.com/ViniciusFM/pybrcode/blob/main/README.md) to see this text in good format. Link: https://github.com/ViniciusFM/pybrcode/blob/main/README.md
What is this library for?
=========================
The **pybrcode** is a python3 library that was built to help people to generate Pix QRCodes (BRCodes) using easy-to-understand and well documented functions. In most scenarios you will only need one function to generate a Pix: `generate_simple_pix(...)`
Go to [How to use?](#how-to-use) section to learn how to use this function.
You can customize the Pix payload
---------------------------------
Although it is easy-to-use, you can customize the Pix payload following the BRCode specification by Central Bank of Brazil (BCB). You can do this by trying to instantiate the `Pix` object by yourself and following the BCB's manuals: [pt-BR](https://www.bcb.gov.br/content/estabilidadefinanceira/SiteAssets/Manual%20do%20BR%20Code.pdf) and [en-US](https://www.bcb.gov.br/content/config/Documents/BR_Code_MANUAL_Version_2_May_2020.pdf)
The custom Pix payload will be generated by fulfilling the "Payload Dictionary" with `Data` tree objects, which can be seen at [pybrcode.pix.Data](pybrcode/pix.py) class. The payload is as follows:
PS: the `crc16` payload field is autogenerated at string conversion of the Pix object (i.e. `str(pix)`). The used CRC algorithm is **CRC-16-CCITT-FFFF** (also called CRC/16-CCITT-FALSE) as described by the BRCode Manual by BCB:
```
Poly=0x1021, Init=0xFFFF, RefIn=false, RefOut=false, XorOut=0x0000
```
```python
class Data(object):
'''This is a Data tree containing a TLV
(type|id, length, value) in each "node".
Convert the object to string to get the
pix payload format'''
def __init__(self, id:int, value:'str|list(Data)'):
self.id = id
self.__length = None
self.value = value
#(code...)
class Pix(object):
'''
Creates a Pix Object that supports image conversion
to "BRCode" format (Pix QRCode). The payload is based
at EMV QRCode model, some of the fields are already
fulfilled according to Pix specifications.
Each field of the payload dict must receive a 'Data'
object, which is a TLV type object. The "optional"
fields are "nullable" fields.
The payload dict contains these informations:
pfi -> Payload Format Indicator (def. 01),
poim -> Point of Initiation Method
(def. 12 - optional),
mai -> Merchant Account Information,
mcc -> Merchant Category Code (def. 0000),
tcurr -> Transaction Currency (def. 986),
tamount -> Transaction Amount (optional),
ccode -> Country Code (def. 58),
mname -> Merchant Name,
mcity -> Merchant City,
pcode -> Postal Code (optional),
adft -> Aditional Data Field Template,
ut -> Unreserved Templates (optional),
crc16 -> Cyclic Redundancy Check 16 bits
Convert the object to string to get the pix payload
format.
The 'crc16' field is automatically generated at
conversion of the Pix object to string __str__.
'''
def __init__(self):
self.payload: dict = {
'pfi' : Data(0, '01'),
'poim' : Data(1, '12'),
'mai' : None,
'mcc' : Data(52, '0000'),
'tcurr' : Data(53, '986'),
'tamount' : None,
'ccode' : Data(58, 'BR'),
'mname' : None,
'mcity' : None,
'pcode' : None,
'adft' : None,
'ut' : None,
'crc16' : None
}
#(code...)
```
Installation
============
Easy way (PyPi repositories) - Not available yet
------------------------------------------------
By writing this line at your favorite terminal you can download the `pybrcode` library to use for your project.
```properties
pip3 install pybrcode
```
**PS: this lib isn't registered at PyPi yet. Please use the [Other Way](#other-way-downloading-this-code) instructions by now.**
Other way (downloading this code)
--------------------------------
You can hit download button or clone this repository to your own project src directory.
Before using this library as a dependency you'll need to download the required libraries to use it. You can do this by writing the line below at your favorite terminal:
```properties
pip3 install -r requirements.txt
```
How to use?
===========
To create your own Pix QRCode all you need, in most cases, is to call the `generate_simple_pix` function. Then you can choose how to export the generated code by calling the following methods of Pix object:
```python
Pix.toBase64(self) # returns a bitmap in a Base64 string.
Pix.toSVG(self) # returns a vector in a SVG string.
Pix.imageToPath(self, destDir:str, filename:str="image", svg:str=False)
# saves a bitmap (PNG) or vector (SVG) in a file at 'destDir'.
Pix.__str__(self) # generate the entire pix payload as string.
```
The `generate_simple_pix` prototype can be seen below:
```python
def generate_simple_pix(
fullname:str, key:str,
city:str, value:float, pix_id:str=None,
pcode:str=None, description:str=None,
mult_transaction:bool=False) -> 'Pix':
'''
raise PixInvalidPayloadException
raise PixInvalidKeyException
This creates a simple functional Pix object.
These are the formats acceptable for keys:
CPF -> ###.###.###-##
CNPJ -> ##.###.###/####-##
Phone -> (##) ####-#### / (##) #####-####
Email -> ###@###.###
RandKey -> len(key) == 36
Information about fields:
* strings will be transformed to lose
accentuation.
fullname -> length [1..25],
key -> will be tested
city -> length [1..15],
value -> rounded to 2 decimals
pix_id -> length [1..25],
* if pix_id omitted, a random
25ch string will be generated.
pcode -> length [1..99] (no treatment)
* pcode is optional
description -> length[1..N]
* N = 73-len(key)
* description is optional
* if len(description) not in [1..N]
description will be discarted.
Returns:
Pix Object
'''
#(code)
```
A simple example using **pybrcode**
-----------------------------------
This example uses all methods and functions mentioned before. You can find this code at [test.py](test.py).
```python
from pybrcode.pix import generate_simple_pix
# This will create a R$ 3,00 pix addressed to:
# 406c5d72-e8e1-40dd-87a9-f7846d08f9e1.
# This pix can accept more than one
# payment (mult_transaction), so you can
# try reading the QRCode to buy me a R$ 3,00
# shot of cachaça :)
pix = generate_simple_pix(
fullname="Vinicius Fonseca Maciel",
key="406c5d72-e8e1-40dd-87a9-f7846d08f9e1",
city="Patos de Minas",
value=3.00,
mult_transaction=True,
description="A shot of cachaça!")
pix.imageToPath('.', filename='testingqrcode', svg=True)
# output image created at ./testingqrcode.svg
pix.imageToPath('.', filename='testingqrcode')
# output image created at ./testingqrcode.png
print(pix.toBase64())
print('-------------------------------------')
# output the base64-str version of png qrcode image
print(pix.toSVG())
print('-------------------------------------')
# output the xml-str version of svg qrcode image
print(pix)
# output the pix code used to produce the qrcode
```
Buy me a shot of cachaça, please?
=================================
If you find this library helpful you're welcome to buy me a shot of cachaça which cost only R$ 3,00 at "Bar do Cabaça"! :D
Just read this BRCode with your bank app:
<img src="./testingqrcode.png" alt="Donate R$ 3,00 by reading this QRCode" width="256">
Raw data
{
"_id": null,
"home_page": "",
"name": "pybrcode",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "python,pix,qrcode,brcode,svg pix qrcode",
"author": "viniciusmacielf (Vin\u00edcius Fonseca Maciel)",
"author_email": "<viniciusmacielf@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e5/6b/450a78c4cd2738964a27456525646c617fca946d6fa53a83b5728d99a4c6/pybrcode-1.1.tar.gz",
"platform": null,
"description": "\r\nGo to github [README.md](https://github.com/ViniciusFM/pybrcode/blob/main/README.md) to see this text in good format. Link: https://github.com/ViniciusFM/pybrcode/blob/main/README.md\r\n\r\nWhat is this library for?\r\n\r\n=========================\r\n\r\n\r\n\r\nThe **pybrcode** is a python3 library that was built to help people to generate Pix QRCodes (BRCodes) using easy-to-understand and well documented functions. In most scenarios you will only need one function to generate a Pix: `generate_simple_pix(...)`\r\n\r\n\r\n\r\nGo to [How to use?](#how-to-use) section to learn how to use this function.\r\n\r\n\r\n\r\nYou can customize the Pix payload\r\n\r\n---------------------------------\r\n\r\n\r\n\r\nAlthough it is easy-to-use, you can customize the Pix payload following the BRCode specification by Central Bank of Brazil (BCB). You can do this by trying to instantiate the `Pix` object by yourself and following the BCB's manuals: [pt-BR](https://www.bcb.gov.br/content/estabilidadefinanceira/SiteAssets/Manual%20do%20BR%20Code.pdf) and [en-US](https://www.bcb.gov.br/content/config/Documents/BR_Code_MANUAL_Version_2_May_2020.pdf)\r\n\r\n\r\n\r\nThe custom Pix payload will be generated by fulfilling the \"Payload Dictionary\" with `Data` tree objects, which can be seen at [pybrcode.pix.Data](pybrcode/pix.py) class. The payload is as follows:\r\n\r\n\r\n\r\nPS: the `crc16` payload field is autogenerated at string conversion of the Pix object (i.e. `str(pix)`). The used CRC algorithm is **CRC-16-CCITT-FFFF** (also called CRC/16-CCITT-FALSE) as described by the BRCode Manual by BCB:\r\n\r\n```\r\n\r\nPoly=0x1021, Init=0xFFFF, RefIn=false, RefOut=false, XorOut=0x0000\r\n\r\n```\r\n\r\n\r\n\r\n```python\r\n\r\nclass Data(object):\r\n\r\n '''This is a Data tree containing a TLV \r\n\r\n (type|id, length, value) in each \"node\".\r\n\r\n Convert the object to string to get the\r\n\r\n pix payload format'''\r\n\r\n def __init__(self, id:int, value:'str|list(Data)'):\r\n\r\n self.id = id\r\n\r\n self.__length = None\r\n\r\n self.value = value\r\n\r\n\r\n\r\n#(code...)\r\n\r\n\r\n\r\nclass Pix(object):\r\n\r\n '''\r\n\r\n Creates a Pix Object that supports image conversion\r\n\r\n to \"BRCode\" format (Pix QRCode). The payload is based \r\n\r\n at EMV QRCode model, some of the fields are already \r\n\r\n fulfilled according to Pix specifications.\r\n\r\n Each field of the payload dict must receive a 'Data'\r\n\r\n object, which is a TLV type object. The \"optional\"\r\n\r\n fields are \"nullable\" fields.\r\n\r\n The payload dict contains these informations:\r\n\r\n pfi -> Payload Format Indicator (def. 01),\r\n\r\n poim -> Point of Initiation Method \r\n\r\n (def. 12 - optional),\r\n\r\n mai -> Merchant Account Information,\r\n\r\n mcc -> Merchant Category Code (def. 0000),\r\n\r\n tcurr -> Transaction Currency (def. 986),\r\n\r\n tamount -> Transaction Amount (optional),\r\n\r\n ccode -> Country Code (def. 58),\r\n\r\n mname -> Merchant Name,\r\n\r\n mcity -> Merchant City,\r\n\r\n pcode -> Postal Code (optional),\r\n\r\n adft -> Aditional Data Field Template,\r\n\r\n ut -> Unreserved Templates (optional),\r\n\r\n crc16 -> Cyclic Redundancy Check 16 bits\r\n\r\n Convert the object to string to get the pix payload\r\n\r\n format.\r\n\r\n The 'crc16' field is automatically generated at\r\n\r\n conversion of the Pix object to string __str__.\r\n\r\n '''\r\n\r\n def __init__(self):\r\n\r\n self.payload: dict = {\r\n\r\n 'pfi' : Data(0, '01'),\r\n\r\n 'poim' : Data(1, '12'),\r\n\r\n 'mai' : None,\r\n\r\n 'mcc' : Data(52, '0000'),\r\n\r\n 'tcurr' : Data(53, '986'),\r\n\r\n 'tamount' : None,\r\n\r\n 'ccode' : Data(58, 'BR'),\r\n\r\n 'mname' : None,\r\n\r\n 'mcity' : None,\r\n\r\n 'pcode' : None,\r\n\r\n 'adft' : None,\r\n\r\n 'ut' : None,\r\n\r\n 'crc16' : None\r\n\r\n }\r\n\r\n\r\n\r\n#(code...)\r\n\r\n```\r\n\r\n\r\n\r\nInstallation\r\n\r\n============\r\n\r\n\r\n\r\nEasy way (PyPi repositories) - Not available yet\r\n\r\n------------------------------------------------\r\n\r\nBy writing this line at your favorite terminal you can download the `pybrcode` library to use for your project.\r\n\r\n```properties\r\n\r\npip3 install pybrcode\r\n\r\n```\r\n\r\n\r\n\r\n**PS: this lib isn't registered at PyPi yet. Please use the [Other Way](#other-way-downloading-this-code) instructions by now.**\r\n\r\n\r\n\r\nOther way (downloading this code)\r\n\r\n--------------------------------\r\n\r\nYou can hit download button or clone this repository to your own project src directory.\r\n\r\n\r\n\r\nBefore using this library as a dependency you'll need to download the required libraries to use it. You can do this by writing the line below at your favorite terminal:\r\n\r\n\r\n\r\n```properties\r\n\r\npip3 install -r requirements.txt\r\n\r\n```\r\n\r\n\r\n\r\nHow to use?\r\n\r\n===========\r\n\r\n\r\n\r\nTo create your own Pix QRCode all you need, in most cases, is to call the `generate_simple_pix` function. Then you can choose how to export the generated code by calling the following methods of Pix object:\r\n\r\n```python\r\n\r\nPix.toBase64(self) # returns a bitmap in a Base64 string.\r\n\r\nPix.toSVG(self) # returns a vector in a SVG string.\r\n\r\nPix.imageToPath(self, destDir:str, filename:str=\"image\", svg:str=False)\r\n\r\n# saves a bitmap (PNG) or vector (SVG) in a file at 'destDir'.\r\n\r\nPix.__str__(self) # generate the entire pix payload as string.\r\n\r\n```\r\n\r\n\r\n\r\nThe `generate_simple_pix` prototype can be seen below:\r\n\r\n\r\n\r\n```python\r\n\r\ndef generate_simple_pix(\r\n\r\n fullname:str, key:str, \r\n\r\n city:str, value:float, pix_id:str=None,\r\n\r\n pcode:str=None, description:str=None,\r\n\r\n mult_transaction:bool=False) -> 'Pix':\r\n\r\n '''\r\n\r\n raise PixInvalidPayloadException\r\n\r\n raise PixInvalidKeyException\r\n\r\n This creates a simple functional Pix object.\r\n\r\n These are the formats acceptable for keys:\r\n\r\n CPF -> ###.###.###-##\r\n\r\n CNPJ -> ##.###.###/####-##\r\n\r\n Phone -> (##) ####-#### / (##) #####-####\r\n\r\n Email -> ###@###.###\r\n\r\n RandKey -> len(key) == 36\r\n\r\n Information about fields:\r\n\r\n * strings will be transformed to lose\r\n\r\n accentuation.\r\n\r\n fullname -> length [1..25],\r\n\r\n key -> will be tested\r\n\r\n city -> length [1..15],\r\n\r\n value -> rounded to 2 decimals\r\n\r\n pix_id -> length [1..25],\r\n\r\n * if pix_id omitted, a random\r\n\r\n 25ch string will be generated.\r\n\r\n pcode -> length [1..99] (no treatment)\r\n\r\n * pcode is optional\r\n\r\n description -> length[1..N]\r\n\r\n * N = 73-len(key)\r\n\r\n * description is optional\r\n\r\n * if len(description) not in [1..N]\r\n\r\n description will be discarted.\r\n\r\n Returns:\r\n\r\n Pix Object\r\n\r\n '''\r\n\r\n\r\n\r\n#(code)\r\n\r\n```\r\n\r\nA simple example using **pybrcode**\r\n\r\n-----------------------------------\r\n\r\n\r\n\r\nThis example uses all methods and functions mentioned before. You can find this code at [test.py](test.py).\r\n\r\n\r\n\r\n```python\r\n\r\nfrom pybrcode.pix import generate_simple_pix\r\n\r\n\r\n\r\n# This will create a R$ 3,00 pix addressed to:\r\n\r\n# 406c5d72-e8e1-40dd-87a9-f7846d08f9e1.\r\n\r\n# This pix can accept more than one \r\n\r\n# payment (mult_transaction), so you can \r\n\r\n# try reading the QRCode to buy me a R$ 3,00\r\n\r\n# shot of cacha\u00e7a :)\r\n\r\npix = generate_simple_pix(\r\n\r\n fullname=\"Vinicius Fonseca Maciel\",\r\n\r\n key=\"406c5d72-e8e1-40dd-87a9-f7846d08f9e1\",\r\n\r\n city=\"Patos de Minas\", \r\n\r\n value=3.00,\r\n\r\n mult_transaction=True,\r\n\r\n description=\"A shot of cacha\u00e7a!\")\r\n\r\n\r\n\r\npix.imageToPath('.', filename='testingqrcode', svg=True)\r\n\r\n# output image created at ./testingqrcode.svg\r\n\r\npix.imageToPath('.', filename='testingqrcode')\r\n\r\n# output image created at ./testingqrcode.png\r\n\r\nprint(pix.toBase64())\r\n\r\nprint('-------------------------------------')\r\n\r\n# output the base64-str version of png qrcode image\r\n\r\nprint(pix.toSVG())\r\n\r\nprint('-------------------------------------')\r\n\r\n# output the xml-str version of svg qrcode image\r\n\r\nprint(pix)\r\n\r\n# output the pix code used to produce the qrcode\r\n\r\n\r\n\r\n```\r\n\r\n\r\n\r\nBuy me a shot of cacha\u00e7a, please?\r\n\r\n=================================\r\n\r\n\r\n\r\nIf you find this library helpful you're welcome to buy me a shot of cacha\u00e7a which cost only R$ 3,00 at \"Bar do Caba\u00e7a\"! :D\r\n\r\n\r\n\r\nJust read this BRCode with your bank app:\r\n\r\n\r\n\r\n<img src=\"./testingqrcode.png\" alt=\"Donate R$ 3,00 by reading this QRCode\" width=\"256\">\r\n\r\n",
"bugtrack_url": null,
"license": "",
"summary": "Generate Pix QRCodes with any type of key",
"version": "1.1",
"split_keywords": [
"python",
"pix",
"qrcode",
"brcode",
"svg pix qrcode"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b0275a25cd1c139372157ca4c1c4145b7aa2e959655558fd4d73efb35e9dae6c",
"md5": "3c03fbb8cb11ecde4c0cc198d1ed166c",
"sha256": "dc2c3983968e475a88108bb3c62187476fbd872dabe15d6e4c2f926ad7ba9f24"
},
"downloads": -1,
"filename": "pybrcode-1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3c03fbb8cb11ecde4c0cc198d1ed166c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 11215,
"upload_time": "2023-04-13T22:12:16",
"upload_time_iso_8601": "2023-04-13T22:12:16.282640Z",
"url": "https://files.pythonhosted.org/packages/b0/27/5a25cd1c139372157ca4c1c4145b7aa2e959655558fd4d73efb35e9dae6c/pybrcode-1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e56b450a78c4cd2738964a27456525646c617fca946d6fa53a83b5728d99a4c6",
"md5": "ff8a323a0ce134dd80f940c632ed4816",
"sha256": "a49f7ee8d4217fe494732129a42230fa91d64a5d440818277c0eff53f23957c1"
},
"downloads": -1,
"filename": "pybrcode-1.1.tar.gz",
"has_sig": false,
"md5_digest": "ff8a323a0ce134dd80f940c632ed4816",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 12742,
"upload_time": "2023-04-13T22:12:18",
"upload_time_iso_8601": "2023-04-13T22:12:18.420286Z",
"url": "https://files.pythonhosted.org/packages/e5/6b/450a78c4cd2738964a27456525646c617fca946d6fa53a83b5728d99a4c6/pybrcode-1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-13 22:12:18",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "pybrcode"
}
JSON