velocity-python 0.0.31__py3-none-any.whl → 0.0.33__py3-none-any.whl

velocity/misc/export.py

@@ -1,143 +1,146 @@
+import decimal
+import json
+from datetime import datetime, date, time, timedelta
+from typing import Union, List, Dict
+from io import BytesIO
+import base64
 import openpyxl
 from openpyxl.styles import NamedStyle, Font, Border, Side, Alignment
 from openpyxl.utils import get_column_letter
-from io import BytesIO
-import base64
 
 
-def extract(d, keys):
-    return [d[key] for key in keys]
+def extract(d: dict, keys: List[str]) -> List:
+    """Extract values from a dictionary based on a list of keys."""
+    return [d.get(key) for key in keys]
 
 
-def autosize_columns(ws, fixed={}):
-    # Try to autosize the columns (doesn't always work due to dynamic
-    # content, font family and font size differences, etc.) There is no
-    # easy way to do this when buiding excel files.
+def autosize_columns(ws, fixed: Dict[str, float] = {}):
+    """Autosize columns in the worksheet based on content length."""
     for col in ws.columns:
         max_length = 0
         for cell in col:
-            try:  # Necessary to avoid error on empty cells
-                if len(str(cell.value)) > max_length:
-                    max_length = len(cell.value)
-            except:
-                pass
+            try:
+                if cell.value and len(str(cell.value)) > max_length:
+                    max_length = len(str(cell.value))
+            except Exception:
+                continue
         adjusted_width = (max_length + 2) * 1.2
-        try:
-            l = get_column_letter(col[0].column)
-            if l in fixed:
-                adjusted_width = fixed["l"]
-            ws.column_dimensions[l].width = adjusted_width
-        except:
-            l = col[0].column
-            if l in fixed:
-                adjusted_width = fixed["l"]
-            ws.column_dimensions[l].width = adjusted_width
+        col_letter = get_column_letter(col[0].column)
+        ws.column_dimensions[col_letter].width = fixed.get(col_letter, adjusted_width)
 
 
 def create_spreadsheet(
-    headers,
-    rows,
+    headers: List[str],
+    rows: List[List],
     fileorbuffer,
-    styles={},
-    merge=[],
-    formats={},
-    named_styles=[],
-    freeze_panes="A2",
-    dimensions=None,
-    auto_size=True,
+    styles: Dict[str, str] = {},
+    merge: List[str] = [],
+    formats: Dict[str, str] = {},
+    named_styles: List[NamedStyle] = [],
+    freeze_panes: str = "A2",
+    dimensions: dict = None,
+    auto_size: bool = True,
 ):
+    """Create an Excel spreadsheet with specified headers, rows, and styles."""
     wb = openpyxl.Workbook()
     ws = wb.active
 
-    local_styles = {}
-
-    style = NamedStyle(name="col_header")
-    style.font = Font(bold=True)
-    style.border = Border(bottom=Side(style="medium", color="000000"))
-    local_styles[style.name] = style
-
-    style = NamedStyle(name="sum_total")
-    style.border = Border(bottom=Side(style="double", color="000000"))
-    local_styles[style.name] = style
-
-    style = NamedStyle(name="sub_total")
-    style.font = Font(bold=True)
-    style.border = Border(bottom=Side(style="thin", color="000000"))
-    local_styles[style.name] = style
-
-    style = NamedStyle(name="bold")
-    style.font = Font(bold=True)
-    local_styles[style.name] = style
-
-    style = NamedStyle(name="align_right")
-    style.font = Font(bold=True)
-    style.border = Border(top=Side(style="thin", color="000000"))
-    style.alignment = Alignment(horizontal="right", vertical="center")
-    local_styles[style.name] = style
-
-    style = NamedStyle(name="align_left")
-    style.font = Font(bold=True)
-    style.border = Border(top=Side(style="thin", color="000000"))
-    style.alignment = Alignment(horizontal="left", vertical="center")
-    local_styles[style.name] = style
-
-    style = NamedStyle(name="align_right_double")
-    style.font = Font(bold=True)
-    style.border = Border(top=Side(style="double", color="000000"))
-    style.alignment = Alignment(horizontal="right", vertical="center")
-    local_styles[style.name] = style
-
-    style = NamedStyle(name="align_left_double")
-    style.font = Font(bold=True)
-    style.border = Border(top=Side(style="double", color="000000"))
-    style.alignment = Alignment(horizontal="left", vertical="center")
-    local_styles[style.name] = style
-
+    # Define default named styles
+    def get_named_styles():
+        named_styles = {
+            "col_header": NamedStyle(
+                name="col_header",
+                font=Font(bold=True),
+                border=Border(bottom=Side(style="medium", color="000000")),
+            ),
+            "sum_total": NamedStyle(
+                name="sum_total",
+                border=Border(bottom=Side(style="double", color="000000")),
+            ),
+            "sub_total": NamedStyle(
+                name="sub_total",
+                font=Font(bold=True),
+                border=Border(bottom=Side(style="thin", color="000000")),
+            ),
+            "bold": NamedStyle(name="bold", font=Font(bold=True)),
+            "align_right": NamedStyle(
+                name="align_right",
+                font=Font(bold=True),
+                border=Border(top=Side(style="thin", color="000000")),
+                alignment=Alignment(horizontal="right", vertical="center"),
+            ),
+            "align_left": NamedStyle(
+                name="align_left",
+                font=Font(bold=True),
+                border=Border(top=Side(style="thin", color="000000")),
+                alignment=Alignment(horizontal="left", vertical="center"),
+            ),
+            "align_right_double": NamedStyle(
+                name="align_right_double",
+                font=Font(bold=True),
+                border=Border(top=Side(style="double", color="000000")),
+                alignment=Alignment(horizontal="right", vertical="center"),
+            ),
+            "align_left_double": NamedStyle(
+                name="align_left_double",
+                font=Font(bold=True),
+                border=Border(top=Side(style="double", color="000000")),
+                alignment=Alignment(horizontal="left", vertical="center"),
+            ),
+        }
+        return named_styles
+
+    # Add default and user-defined styles
+    local_styles = get_named_styles()
     for style in named_styles:
         local_styles[style.name] = style
-
     for style in local_styles.values():
         wb.add_named_style(style)
 
+    # Add headers and rows
     ws.append(headers)
+    for row in rows:
+        ws.append(row)
 
-    [ws.append(row) for row in rows]
-
-    if freeze_panes:
-        ws.freeze_panes = freeze_panes
+    # Set freeze panes
+    ws.freeze_panes = freeze_panes
 
+    # Auto-size columns if enabled
     if auto_size:
-        autosize_columns(ws)
+        autosize_columns(ws, fixed={})
 
+    # Set row and column dimensions if provided
     if dimensions:
         for key, val in dimensions.get("rows", {}).items():
             ws.row_dimensions[key].height = val
         for key, val in dimensions.get("columns", {}).items():
             ws.column_dimensions[key].width = val
 
-    for cell, style in styles.items():
-        ws[cell].style = style
-
+    # Apply cell styles, merges, and formats
+    for cell, style_name in styles.items():
+        if style_name in local_styles:
+            ws[cell].style = local_styles[style_name]
     for cell_range in merge:
         ws.merge_cells(cell_range)
+    for cell, format_code in formats.items():
+        ws[cell].number_format = format_code
 
-    for cell, format in formats.items():
-        ws[cell].number_format = format
-
+    # Save workbook to the provided file or buffer
     wb.save(fileorbuffer)
 
 
-def getDownloadableSpreadsheet(
-    headers,
-    rows,
-    styles={},
-    merge=[],
-    formats={},
-    named_styles=[],
-    freeze_panes="A2",
-    dimensions=None,
-    auto_size=True,
-):
+def get_downloadable_spreadsheet(
+    headers: List[str],
+    rows: List[List],
+    styles: Dict[str, str] = {},
+    merge: List[str] = [],
+    formats: Dict[str, str] = {},
+    named_styles: List[NamedStyle] = [],
+    freeze_panes: str = "A2",
+    dimensions: dict = None,
+    auto_size: bool = True,
+) -> str:
+    """Generate a downloadable spreadsheet encoded in base64."""
     buffer = BytesIO()
     create_spreadsheet(
         headers,

velocity/misc/format.py

@@ -1,47 +1,45 @@
 import decimal
 import json
 from datetime import datetime, date, time, timedelta
+from typing import Union
 
 
-def gallons(data):
+def gallons(data: Union[None, str, float, decimal.Decimal]) -> str:
+    """Converts a value to a string formatted in gallons with two decimal places."""
     if data is None:
         return ""
-    data = decimal.Decimal(data)
-    return "{:.2f}".format(data)
-    # return "{:1,.2f} gals".format(data)
+    try:
+        data = decimal.Decimal(data)
+        return f"{data:.2f}"
+    except (decimal.InvalidOperation, ValueError, TypeError):
+        return ""  # Return an empty string for invalid input
 
 
-def gallons2liters(data):
+def gallons2liters(data: Union[None, str, float, decimal.Decimal]) -> str:
+    """Converts gallons to liters and formats with two decimal places."""
     if data is None:
         return ""
-    data = decimal.Decimal(data) * decimal.Decimal(3.78541)
-    return "{:.2f}".format(data)
-    # return "{:1,.2f} liters".format(data)
+    try:
+        data = decimal.Decimal(data) * decimal.Decimal("3.78541")
+        return f"{data:.2f}"
+    except (decimal.InvalidOperation, ValueError, TypeError):
+        return ""
 
 
-def currency(data):
+def currency(data: Union[None, str, float, decimal.Decimal]) -> str:
+    """Formats a value as currency with two decimal places."""
     if data is None:
         return ""
-    decimal.Decimal(data)
-    return "{:.2f}".format(data)
-    # return "${:1,.2f}".format(data)
+    try:
+        data = decimal.Decimal(data)
+        return f"{data:.2f}"
+    except (decimal.InvalidOperation, ValueError, TypeError):
+        return ""
 
 
-def human_delta(tdelta):
-    """
-    Takes a timedelta object and formats it for humans.
-    Usage:
-        # 149 day(s) 8 hr(s) 36 min 19 sec
-        print(human_delta(datetime(2014, 3, 30) - datetime.now()))
-    Example Results:
-        23 sec
-        12 min 45 sec
-        1 hr(s) 11 min 2 sec
-        3 day(s) 13 hr(s) 56 min 34 sec
-    :param tdelta: The timedelta object.
-    :return: The human formatted timedelta
-    """
-    d = dict(days=tdelta.days)
+def human_delta(tdelta: timedelta) -> str:
+    """Formats a timedelta object into a human-readable format."""
+    d = {"days": tdelta.days, "hrs": 0, "min": 0, "sec": 0}
     d["hrs"], rem = divmod(tdelta.seconds, 3600)
     d["min"], d["sec"] = divmod(rem, 60)
 
@@ -57,26 +55,25 @@ def human_delta(tdelta):
     return fmt.format(**d)
 
 
-def to_json(o, datefmt="%Y-%m-%d", timefmt="%H:%M:%S"):
+def to_json(o, datefmt: str = "%Y-%m-%d", timefmt: str = "%H:%M:%S") -> str:
+    """Serializes an object to JSON, handling special types like Decimal and datetime."""
+
     class JsonEncoder(json.JSONEncoder):
-        def default(self, o):
-            if hasattr(o, "to_json"):
-                return o.to_json()
-            elif o is None:
-                return 0
-            elif isinstance(o, decimal.Decimal):
-                return float(o)
-            elif isinstance(o, date):
-                return o.strftime(datefmt)
-            elif isinstance(o, datetime):
-                return o.strftime("{} {}".format(datefmt, timefmt))
-            elif isinstance(o, time):
-                return o.strftime(timefmt)
-            elif isinstance(o, timedelta):
-                return human_delta(o)
-            try:
-                return super(JsonEncoder, self).default(o)
-            except:
-                return str(o)
+        def default(self, obj):
+            if hasattr(obj, "to_json"):
+                return obj.to_json()
+            elif obj is None:
+                return None
+            elif isinstance(obj, decimal.Decimal):
+                return float(obj)
+            elif isinstance(obj, date):
+                return obj.strftime(datefmt)
+            elif isinstance(obj, datetime):
+                return obj.strftime(f"{datefmt} {timefmt}")
+            elif isinstance(obj, time):
+                return obj.strftime(timefmt)
+            elif isinstance(obj, timedelta):
+                return human_delta(obj)
+            return super().default(obj)
 
     return json.dumps(o, cls=JsonEncoder)

velocity/misc/mail.py

@@ -1,74 +1,78 @@
 #!/usr/local/bin/python
 from email.parser import Parser as EmailParser
-from io import BytesIO
-import mimetypes, hashlib
+from email.message import Message
+from typing import List, Optional
+import mimetypes
+import hashlib
 
 
 class NotSupportedMailFormat(Exception):
+    """Exception raised for unsupported mail formats."""
+
     pass
 
 
-def get_full_emails(addresses):
+class Attachment:
+    """Represents an email attachment."""
+
+    def __init__(self, name: str, data: bytes):
+        self.name = name
+        self.data = data
+        self.ctype = mimetypes.guess_type(name)[0] or "application/octet-stream"
+        self.size = len(data)
+        self.hash = hashlib.sha1(data).hexdigest()
+
+
+def get_full_emails(addresses: List) -> List[str]:
+    """Generates a list of formatted email addresses with names."""
     results = []
     for a in addresses:
-        if a.name:
-            results.append(
-                f"{a.name.decode('utf-8')} <{a.mailbox.decode('utf-8')}@{a.host.decode('utf-8')}>"
-            )
+        mailbox = a.mailbox.decode("utf-8")
+        host = a.host.decode("utf-8")
+        name = a.name.decode("utf-8") if a.name else None
+        if name:
+            results.append(f"{name} <{mailbox}@{host}>")
         else:
-            results.append(f"{a.mailbox.decode('utf-8')}@{a.host.decode('utf-8')}")
+            results.append(f"{mailbox}@{host}")
     return results
 
 
-def get_address_only(addresses):
-    results = []
-    for a in addresses:
-        results.append(f"{a.mailbox.decode('utf-8')}@{a.host.decode('utf-8')}")
-    return results
+def get_address_only(addresses: List) -> List[str]:
+    """Generates a list of email addresses without names."""
+    return [f"{a.mailbox.decode('utf-8')}@{a.host.decode('utf-8')}" for a in addresses]
 
 
-def parse_attachment(part):
+def parse_attachment(part: Message) -> Optional[Attachment]:
+    """Parses an attachment from a message part if present."""
     content_disposition = part.get("Content-Disposition")
     if content_disposition:
         dispositions = content_disposition.strip().split(";")
-        if content_disposition and dispositions[0].lower() == "attachment":
+        if dispositions[0].lower() == "attachment":
             name = part.get_filename()
-            if not name:
-                return None
             data = part.get_payload(decode=True)
-            if not data:
-                return None
-            attachment = Object()
-            attachment.data = data
-            attachment.ctype = mimetypes.guess_type(name)[0]
-            attachment.size = len(data)
-            attachment.name = name
-            attachment.hash = hashlib.sha1(data).hexdigest()
-
-            return attachment
-
+            if name and data:
+                return Attachment(name=name, data=data)
     return None
 
 
-def parse(content):
-    body = None
-    html = None
+def parse(content: str) -> dict:
+    """Parses the email content and extracts plain text, HTML, and attachments."""
+    body = bytearray()
+    html = bytearray()
     attachments = []
-    for part in EmailParser().parsestr(content).walk():
+
+    message = EmailParser().parsestr(content)
+    for part in message.walk():
         attachment = parse_attachment(part)
         if attachment:
             attachments.append(attachment)
         elif part.get_content_type() == "text/plain":
-            if body is None:
-                body = bytes()
-            body += part.get_payload(decode=True)
+            body.extend(part.get_payload(decode=True) or b"")
         elif part.get_content_type() == "text/html":
-            if html is None:
-                html = bytes()
-            html += part.get_payload(decode=True)
+            html.extend(part.get_payload(decode=True) or b"")
 
     return {
-        "body": body,
-        "html": html,
+        "body": body.decode("utf-8") if body else None,
+        "html": html.decode("utf-8") if html else None,
         "attachments": attachments,
     }

velocity/misc/merge.py

@@ -1,36 +1,52 @@
 from copy import deepcopy
 from functools import reduce
+from typing import Dict, List, Any
 
 
-def deep_merge(*dicts, update=False):
+def deep_merge(*dicts: Dict[str, Any], update: bool = False) -> Dict[str, Any]:
     """
-    Merges dicts deeply.
+    Deeply merges multiple dictionaries.
+
     Parameters
     ----------
-    dicts : list[dict]
-        List of dicts.
-    update : bool
-        Whether to update the first dict or create a new dict.
+    *dicts : Dict[str, Any]
+        Variable number of dictionaries to merge.
+    update : bool, optional
+        If True, updates the first dictionary in-place.
+        If False, creates and returns a new merged dictionary. Default is False.
+
     Returns
     -------
-    merged : dict
-        Merged dict.
+    Dict[str, Any]
+        The merged dictionary.
+
+    Notes
+    -----
+    - If a key's value in two dictionaries is a dictionary, they are merged recursively.
+    - If a key's value in two dictionaries is a list, values from the second list
+      are added to the first, avoiding duplicates.
+    - For all other types, the value from the latter dictionary overwrites the former.
     """
 
-    def merge_into(d1, d2):
-        for key in d2:
+    def merge_into(d1: Dict[str, Any], d2: Dict[str, Any]) -> Dict[str, Any]:
+        for key, value in d2.items():
             if key not in d1:
-                d1[key] = deepcopy(d2[key])
-            elif isinstance(d1[key], dict):
-                d1[key] = merge_into(d1[key], d2[key])
-            elif isinstance(d1[key], list) and isinstance(d2[key], list):
-                d1[key].extend(d2[key])
+                d1[key] = deepcopy(value)
+            elif isinstance(d1[key], dict) and isinstance(value, dict):
+                d1[key] = merge_into(d1[key], value)
+            elif isinstance(d1[key], list) and isinstance(value, list):
+                existing_items = set(d1[key])
+                d1[key].extend(x for x in value if x not in existing_items)
+                existing_items.update(
+                    value
+                )  # Keep the set updated for further iterations
             else:
-                d1[key] = deepcopy(d2[key])
-
+                d1[key] = deepcopy(value)  # Overwrite with the new value
         return d1
 
     if update:
+        # Update the first dictionary in-place
         return reduce(merge_into, dicts[1:], dicts[0])
     else:
+        # Create a new dictionary for the merged result
         return reduce(merge_into, dicts, {})

velocity/misc/timer.py

@@ -1,27 +1,50 @@
 import time
+from typing import Optional
 
 
 class Timer:
-    def __init__(self, label="Timer"):
+    def __init__(self, label: str = "Timer"):
+        """
+        Initializes a Timer instance with an optional label and starts the timer.
+        """
         self._label = label
+        self._start: Optional[float] = None
+        self._end: Optional[float] = None
+        self._diff: Optional[float] = None
         self.start()
 
-    def start(self):
-        self._end = self._start = time.time()
-        self._diff = 0
+    def start(self) -> None:
+        """Starts or restarts the timer."""
+        self._start = time.time()
+        self._end = None
+        self._diff = None
 
-    def end(self):
+    def stop(self) -> float:
+        """Stops the timer and calculates the time elapsed."""
+        if self._start is None:
+            raise ValueError("Timer has not been started.")
         self._end = time.time()
         self._diff = self._end - self._start
+        return self._diff
 
-    def __str__(self):
-        if not self._diff:
-            self.end()
-        return f"{self._label}: {self._diff:.4f} s"
+    def elapsed(self) -> float:
+        """Returns the elapsed time in seconds without stopping the timer."""
+        if self._start is None:
+            raise ValueError("Timer has not been started.")
+        return time.time() - self._start
+
+    def __str__(self) -> str:
+        """Returns a string representation of the time elapsed or final time."""
+        if self._diff is not None:  # Timer has been stopped
+            return f"{self._label}: {self._diff:.4f} s"
+        else:  # Timer is still running, show elapsed time
+            return f"{self._label}: {self.elapsed():.4f} s"
 
 
 if __name__ == "__main__":
     t = Timer("My Label")
     time.sleep(0.003)
+    print(t)  # Should display elapsed time
     time.sleep(3)
-    print(t)
+    t.stop()
+    print(t)  # Should display the stopped time (final diff)

{velocity_python-0.0.31.dist-info → velocity_python-0.0.33.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: velocity-python
-Version: 0.0.31
+Version: 0.0.33
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Paul Perez <pperez@codeclubs.org>
 Project-URL: Homepage, https://codeclubs.org/projects/velocity