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,22 +148,74 @@ 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):
+    """
+    Invoice Class.
+
+    This class provides methods for interacting with invoices in the SuperFaktura API.
+    It allows for retrieving, creating, updating, and deleting invoices.
+
+    Methods:
+        - add: Creates a new invoice.
+        - get: Retrieves an invoice by ID.
+        - list: Retrieves a list of invoices.
+        - update: Updates an existing invoice.
+
+    Usage:
+        invoice = Invoice()
+        invoice.add(
+            invoice=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,
+            ),
+        )
+    """
+
     def __init__(self):
         super().__init__()
 
     def add(
         self,
-        invoice: InvoiceModel,
+        invoice_model: InvoiceModel,
         items: List[InvoiceItem],
         contact: ClientContactModel,
     ):
+        """Creates a new invoice."""
         data = {
-            "Invoice": invoice.as_dict(),
+            "Invoice": invoice_model.as_dict(),
             "InvoiceItem": [item.as_dict() for item in items],
             "Client": contact.as_dict(),
         }
@@ -116,7 +228,7 @@ if __name__ == "__main__":
     invoice = Invoice()
     bank = BankAccount()
     invoice.add(
-        invoice=InvoiceModel(
+        invoice_model=InvoiceModel(
             type=InvoiceType.PROFORMA,
             name="Invoice 3",
             due=Date("2025-02-01"),