From fa3d2ddf328e5ff679a0d0da1c1f5103da070165 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Richard=20Kub=C3=AD=C4=8Dek?= Date: Fri, 28 Feb 2025 19:11:20 +0100 Subject: [PATCH] examples: add get_country_list and add_invoice --- examples/add_invoice.py | 72 ++++++++++++++++++++++++++++++++++++ examples/get_country_list.py | 18 +++++++++ examples/tools.py | 13 +++++-- superfaktura/invoice.py | 70 +++++++++++++++-------------------- 4 files changed, 129 insertions(+), 44 deletions(-) create mode 100644 examples/add_invoice.py create mode 100644 examples/get_country_list.py diff --git a/examples/add_invoice.py b/examples/add_invoice.py new file mode 100644 index 0000000..130f618 --- /dev/null +++ b/examples/add_invoice.py @@ -0,0 +1,72 @@ +""" +Main script to add an invoice and save it as a PDF using the SuperFaktura API. + +This script demonstrates how to create an invoice with multiple items, +retrieve the invoice as a PDF, and save the PDF to a file. + +Usage: + Run this script directly to create and save an invoice PDF. + +Dependencies: + - examples.tools.save_file_as_pdf + - superfaktura.bank_account.BankAccount + - superfaktura.client_contacts.ClientContactModel + - superfaktura.enumerations.currency.Currencies + - superfaktura.enumerations.language.Language + - superfaktura.invoice.Invoice + - superfaktura.invoice.InvoiceModel + - superfaktura.invoice.InvoiceType + - superfaktura.invoice.InvoiceItem + - superfaktura.invoice.InvoiceSettings + - superfaktura.utils.data_types.Date +""" + +from examples.tools import save_file_as_pdf +from superfaktura.bank_account import BankAccount +from superfaktura.client_contacts import ClientContactModel +from superfaktura.enumerations.currency import Currencies +from superfaktura.enumerations.language import Language +from superfaktura.invoice import ( + Invoice, + InvoiceModel, + InvoiceType, + InvoiceItem, + InvoiceSettings, +) +from superfaktura.utils.data_types import Date + + +if __name__ == "__main__": + invoice = Invoice() + bank = BankAccount() + resp = invoice.add( + invoice_model=InvoiceModel( + type=InvoiceType.INVOICE, + name="My First Invoice", + due=Date("2025-04-01"), + invoice_currency=Currencies.EUR, + header_comment="We invoice you for services", + bank_accounts=[bank.default().as_dict()], + ), + items=[ + InvoiceItem( + name="Website Development", unit_price=1000.0, quantity=1, tax=20 + ), + InvoiceItem( + name="Hosting Service (1 year)", unit_price=500.0, quantity=1, tax=20 + ), + ], + contact=ClientContactModel( + name="John Doe", + email="john.doe@examle.com", + phone="+1 555-1234", + address="123 Main Street, New York", + ico="987654321", + update=True, + country_id=225, + ), + invoice_settings=InvoiceSettings(language=Language.English), + ) + _pdf = invoice.get_pdf(invoice=resp, language=Language.English) + + save_file_as_pdf(_pdf, "invoice.pdf") diff --git a/examples/get_country_list.py b/examples/get_country_list.py new file mode 100644 index 0000000..208a7c8 --- /dev/null +++ b/examples/get_country_list.py @@ -0,0 +1,18 @@ +""" +This script retrieves and prints the list of countries using the SuperFaktura API. +""" + +from pprint import pprint + +from superfaktura.utils.country import country_list + + +def main(): + """ + Main function to retrieve and print the list of countries using the SuperFaktura API. + """ + pprint(country_list()) + + +if __name__ == "__main__": + main() diff --git a/examples/tools.py b/examples/tools.py index 78ceddf..3a56cc9 100644 --- a/examples/tools.py +++ b/examples/tools.py @@ -1,7 +1,14 @@ +""" +This module contains tools for working with these examples. +""" -def save_file_as_pdf( - input_data: bytes, output_path: str = "output.pdf" -) -> None: +def save_file_as_pdf(input_data: bytes, output_path: str = "output.pdf") -> None: + """ + Save the input data as a PDF file. + :param input_data: + :param output_path: + :return: + """ with open(output_path, "wb") as f: f.write(input_data) diff --git a/superfaktura/invoice.py b/superfaktura/invoice.py index 09e8cb1..df85c5e 100644 --- a/superfaktura/invoice.py +++ b/superfaktura/invoice.py @@ -56,13 +56,10 @@ from dataclasses import dataclass, asdict from typing import Optional, List import json -from superfaktura.bank_account import BankAccount from superfaktura.client_contacts import ClientContactModel -from superfaktura.enumerations.currency import Currencies from superfaktura.enumerations.data_format import DataFormat from superfaktura.enumerations.language import Language from superfaktura.superfaktura_api import SuperFakturaAPI -from superfaktura.utils import save_temporary_file_as_pdf from superfaktura.utils.data_types import Date, DateEncoder @@ -168,6 +165,31 @@ class InvoiceRespModel: invoice_token: Optional[str] = None +@dataclass +class InvoiceSettings: + """ + This dataclass represents the settings for an invoice in the SuperFaktura API. + """ + + language: Optional[str] = None + bysquare: Optional[bool] = None + callback_payment: Optional[str] = None + online_payment: Optional[bool] = None + payment_info: Optional[bool] = None + paypal: Optional[bool] = None + show_prices: Optional[bool] = None + signature: Optional[bool] = None + summary_bg_color: Optional[str] = None + + def as_dict(self) -> dict: + """Returns a dictionary representation of the ClientContactModel.""" + data = asdict(self) + for key in list(data.keys()): + if data[key] is None: + del data[key] + return data + + class InvoiceType: """ Invoice Type Enumeration. @@ -233,6 +255,7 @@ class Invoice(SuperFakturaAPI): invoice_model: InvoiceModel, items: List[InvoiceItem], contact: ClientContactModel, + invoice_settings: Optional[InvoiceSettings], ) -> InvoiceRespModel: """ Adds a new invoice. @@ -241,9 +264,11 @@ class Invoice(SuperFakturaAPI): invoice_model (InvoiceModel): The invoice model. items (List[InvoiceItem]): List of invoice items. contact (ClientContactModel): The client contact model. + invoice_settings (Optional[InvoiceSettings]): The invoice settings. Returns: InvoiceRespModel: The response model for the invoice. + :param invoice_settings: :param contact: :param items: :param invoice_model: @@ -252,6 +277,7 @@ class Invoice(SuperFakturaAPI): "Invoice": invoice_model.as_dict(), "InvoiceItem": [item.as_dict() for item in items], "Client": contact.as_dict(), + "InvoiceSetting": invoice_settings.as_dict(), } url = "invoices/create" resp = self.post(endpoint=url, data=json.dumps(data, cls=DateEncoder)) @@ -280,41 +306,3 @@ class Invoice(SuperFakturaAPI): url = f"{language}/invoices/pdf/{invoice.invoice_id}/token:{invoice.invoice_token}" document = self.get(url, data_format=DataFormat.PDF)["pdf"] return document - - -if __name__ == "__main__": - invoice = Invoice() - bank = BankAccount() - resp = invoice.add( - invoice_model=InvoiceModel( - type=InvoiceType.PROFORMA, - name="Invoice 8", - due=Date("2025-04-01"), - invoice_currency=Currencies.CZK, - header_comment="We invoice you for services", - bank_accounts=[bank.default().as_dict()], - ), - items=[ - InvoiceItem(name="Services", unit_price=100, quantity=5, unit="ks", tax=21), - InvoiceItem(name="SIM card", unit_price=50, quantity=1, tax=21, unit="ks"), - InvoiceItem( - name="SIM card 2", unit_price=75, quantity=1, tax=21, unit="ks" - ), - ], - contact=ClientContactModel( - name="Richard Kubíček", - email="kubicekr@eledio.com", - phone="+420 123 456 789", - address="Jaroslava Foglara 861/1", - ico="123", - update=True, - country_id=57, - ), - ) - _pdf = invoice.get_pdf(resp) - - save_temporary_file_as_pdf(_pdf, "invoice.pdf") - - from pprint import pprint - - pprint(resp)