Merge pull request #42 from westnetz/feature/docstrings

added docstrings

Author: olf42

rechnung/contract.py

@@ -8,6 +8,11 @@
 
 
 def get_contracts(settings, year=None, month=None, cid_only=None, inactive=False):
+    """
+    Fetches all contracts from the settings.contracts_dir directory.
+    Returns a dict with all active contracts, i.e. contracts with started
+    in the past.
+    """
     contracts = OrderedDict()
     for filename in settings.contracts_dir.glob("*.yaml"):
         if cid_only and cid_only != filename.stem:
@@ -28,6 +33,9 @@ def get_contracts(settings, year=None, month=None, cid_only=None, inactive=False
 
 
 def render_contracts(settings):
+    """
+    Renders all contracts as pdfs to settings.contracts_dir
+    """
     template = get_template(settings.contract_template_file)
     logo_path = settings.assets_dir / "logo.png"
 
@@ -60,6 +68,12 @@ def render_contracts(settings):
 
 
 def send_contract(settings, cid):
+    """
+    Sends the contract specified with the cid via email to the customer.
+
+    If set, the policy and the product description of the main product 
+    will be attached.
+    """
     mail_template = get_template(settings.contract_mail_template_file)
     contract_pdf_path = Path(settings.contracts_dir) / f"{cid}.pdf"
     contract_yaml_filename = Path(settings.contracts_dir) / f"{cid}.yaml"

rechnung/invoice.py

@@ -7,6 +7,10 @@
 
 
 def fill_invoice_items(settings, items):
+    """
+    Calculates the items which will appear on the invoice, as well as the total_gross,
+    total_net and total_vat value.
+    """
     invoice_total_net = float()
     invoice_total_vat = float()
     invoice_total_gross = float()
@@ -36,6 +40,13 @@ def fill_invoice_items(settings, items):
 
 
 def generate_invoice(settings, contract, year, month):
+    """
+    Creates an invoice, i.e. calls the fill_invoice_items function, to get
+    all the numbers right, as well as filling all the remaining required meta
+    information about the customer.
+
+    It returns the invoice dict.
+    """
     invoice_items, net, vat, gross = fill_invoice_items(settings, contract["items"])
 
     invoice_data = {}
@@ -68,6 +79,9 @@ def iterate_invoices(settings):
 
 
 def render_invoices(settings):
+    """
+    Renders all invoices and saves pdfs to settings.invoices_dir.
+    """
     template = get_template(settings.invoice_template_file)
 
     for contract_invoice_dir, filename in iterate_invoices(settings):
@@ -98,6 +112,9 @@ def render_invoices(settings):
 
 
 def save_invoice_yaml(settings, invoice_data, force=False):
+    """
+    Saves the invoice_data to a yaml file in settings.invoices_dir.
+    """
     invoice_contract_dir = settings.invoices_dir / invoice_data["cid"]
 
     if not invoice_contract_dir.is_dir():
@@ -112,6 +129,9 @@ def save_invoice_yaml(settings, invoice_data, force=False):
 
 
 def create_invoices(settings, year, month, cid_only=None, force=False):
+    """
+    Bulk creates invoice yaml files for a specific month-year-combination.
+    """
     if force:
         print("Force create enabled")
 
@@ -126,6 +146,9 @@ def create_invoices(settings, year, month, cid_only=None, force=False):
 
 
 def send_invoices(settings, year, month, cid_only, force):
+    """
+    Sends emails with the invoices as attachment.
+    """
     mail_template = get_template(settings.invoice_mail_template_file)
 
     if force:

rechnung/settings.py

@@ -52,10 +52,18 @@
 
 
 class UnknownSettingError(Exception):
+    """
+    If a setting is found in the settings.yaml file which is unknown to rechnung, this exception is thrown.
+    """
+
     pass
 
 
 class RequiredSettingMissingError(Exception):
+    """
+    If a setting is missing, but required to be set in the settings.yaml, this exception is thrown.
+    """
+
     pass
 
 

rechnung/tests/test_cli.py

@@ -153,8 +153,9 @@ def test_invoice_create_cid_only(cli_test_data_path):
     cli1, path = cli_test_data_path
     s = settings.get_settings_from_cwd(path)
     runner = CliRunner()
-    result = runner.invoke(cli1, ["create-invoices", "2019", "10", "--cid-only=1000",
-    "--force-recreate"])
+    result = runner.invoke(
+        cli1, ["create-invoices", "2019", "10", "--cid-only=1000", "--force-recreate"]
+    )
     assert "1002" not in result.output
     assert "already exists" not in result.output