ggblab 0.9.3__py3-none-any.whl

ggblab/schema.py

@@ -0,0 +1,114 @@
+import requests
+import os
+import xmlschema
+import io
+# from pprint import pprint
+
+class ggb_schema:
+    """GeoGebra XML schema loader and validator.
+    
+    Manages the GeoGebra XML schema (XSD) for validating and parsing .ggb
+    construction files. The schema is automatically downloaded from the
+    official GeoGebra site and cached locally for offline use.
+    
+    The schema enables:
+    - XML validation of GeoGebra constructions
+    - Conversion between XML and Python dictionaries
+    - Type-safe parsing of construction elements
+    
+    Attributes:
+        url (str): URL of the GeoGebra common.xsd schema file
+        local_path (str): Local cache path for the downloaded schema
+        schema_content (str): Raw XSD content as string
+        schema (xmlschema.XMLSchema): Compiled schema object for validation
+    
+    Example:
+        >>> schema = ggb_schema()
+        >>> # Schema is loaded and ready for use
+        >>> data_dict = schema.schema.to_dict(xml_string)
+    
+    Note:
+        The schema is downloaded once and cached in xsd/common.xsd.
+        Delete the cache to force re-download on next instantiation.
+    """
+    url = 'http://www.geogebra.org/apps/xsd/common.xsd'
+    local_path = 'xsd/common.xsd'
+
+    def __init__(self):
+        """Initialize the schema loader and load/cache the XSD file.
+        
+        Downloads the GeoGebra schema from the official URL if not already
+        cached locally. Creates the cache directory if it doesn't exist.
+        
+        Raises:
+            xmlschema.validators.exceptions.XMLSchemaValidationError: If schema is invalid.
+            Exception: If schema download or loading fails.
+        """
+        # Ensure the cache directory exists
+        os.makedirs(os.path.dirname(self.local_path), exist_ok=True)
+        self.schema_content = cache_schema_locally(self.url, self.local_path)
+
+        # Assuming you have a geogebra.xml file (from an unzipped .ggb file)
+        # and the XSD files (ggb.xsd and common.xsd) downloaded locally
+        # or you can use the URL for the schema
+
+        # Create a schema instance (it automatically handles imported common.xsd)
+        try:
+            self.schema = xmlschema.XMLSchema(io.StringIO(self.schema_content))
+
+            # Convert the XML data to a Python dictionary
+            # data_dict = ggb_schema.to_dict(io.StringIO(r))
+
+            # Pretty print the resulting dictionary
+            # pprint(data_dict)
+
+        except xmlschema.validators.exceptions.XMLSchemaValidationError as e:
+            print(f"XML validation error: {e}")
+        except Exception as e:
+            print(f"An error occurred: {e}")
+
+
+def cache_schema_locally(schema_url, local_file_path):
+    """Download and cache a schema file from URL.
+    
+    Downloads an XML schema from the specified URL and saves it to a local
+    file for offline use. If the file already exists, uses the cached version
+    instead of re-downloading.
+    
+    Args:
+        schema_url (str): URL of the schema file to download.
+        local_file_path (str): Path where the schema should be cached.
+    
+    Returns:
+        str: Content of the schema file, or None if download fails.
+    
+    Examples:
+        >>> content = cache_schema_locally(
+        ...     'http://example.com/schema.xsd',
+        ...     'cache/schema.xsd'
+        ... )
+        Using local cached file: cache/schema.xsd
+    
+    Note:
+        Future enhancement: Add logic to check file age or Last-Modified
+        header to refresh stale cached schemas.
+    """
+    if os.path.exists(local_file_path):
+        print(f"Using local cached file: {local_file_path}")
+        with open(local_file_path, 'r', encoding='utf-8') as f:
+            return f.read()
+
+    print(f"Local file not found. Downloading from: {schema_url}")
+    try:
+        response = requests.get(schema_url)
+        response.raise_for_status()  # Raise an exception for bad status codes
+
+        # Save the content to the local file
+        with open(local_file_path, 'w', encoding='utf-8') as f:
+            f.write(response.text)
+        print(f"Successfully downloaded and saved to: {local_file_path}")
+        return response.text
+
+    except requests.exceptions.RequestException as e:
+        print(f"Error downloading schema: {e}")
+        return None

ggblab/utils.py

@@ -0,0 +1,109 @@
+"""Common utility functions for ggblab.
+
+Python's Design Grievances
+==========================
+
+This module exists because Python's standard library refuses to include basic
+utilities that every developer needs. Here are some legitimate complaints:
+
+1. **flatten() is not standardized**
+   
+   Despite being one of the most common operations, Python forces you to either:
+   - Use itertools.chain.from_iterable() (only 1-level deep)
+   - Install more-itertools (external dependency)
+   - Write it yourself every single time
+   
+   JavaScript has Array.flat(). Why doesn't Python have list.flatten()?
+   
+   The excuse: "Strings are iterable, so it's ambiguous."
+   The reality: This is a solvable problem. Just treat str/bytes as atomic by default.
+   
+2. **String as Iterable: The Perpetual Footgun**
+   
+   str being iterable causes endless bugs:
+   
+   >>> def process(items):
+   ...     return [x for item in items for x in item]
+   >>> process(['abc', 'def'])  # Expected: ['abc', 'def']
+   ['a', 'b', 'c', 'd', 'e', 'f']  # Oops!
+   
+   We have to write `isinstance(x, (str, bytes))` checks EVERYWHERE.
+   This is a design flaw, not a feature.
+   
+3. **Pattern Matching Underutilized (Since Python 3.10)**
+   
+   Python 3.10 introduced structural pattern matching with beautiful tuple unpacking:
+   
+   >>> match edges:
+   ...     case []:
+   ...         return "no edges"
+   ...     case [single]:
+   ...         return f"one edge: {single}"
+   ...     case [first, second]:
+   ...         return f"two edges: {first}, {second}"
+   ...     case [first, *rest]:
+   ...         return f"multiple edges starting with {first}"
+   
+   Yet most Python code still uses:
+   - if len(edges) == 0: ...
+   - if len(edges) == 1: x = edges[0]; ...
+   - if len(edges) >= 2: first, second = edges[0], edges[1]; ...
+   
+   Why? Because Python educators haven't caught up with modern features.
+   The language evolves, but teaching materials stay stuck in 2015.
+   
+4. **Education Gap: Modern Python Features Ignored**
+   
+   Python keeps adding excellent features that go unused:
+   - Walrus operator (:=) for cleaner loops
+   - Union types (X | Y instead of Union[X, Y])
+   - Structural pattern matching (match/case)
+   - Positional-only parameters (def f(x, /))
+   
+   But most tutorials, Stack Overflow answers, and even production code
+   still use ancient patterns. This is educator negligence, plain and simple.
+   
+   If you introduce a feature, TEACH IT. Otherwise, what's the point?
+
+Now, the actual utilities:
+"""
+
+from collections.abc import Iterable
+
+
+def flatten(items):
+    """Recursively flatten nested iterables.
+    
+    Converts nested structures like [[1, [2, 3]], 4] into [1, 2, 3, 4].
+    Strings and bytes are treated as atomic elements (not iterated).
+    
+    Note: This function exists because Python refuses to standardize it.
+          Yes, we have to explicitly check for str/bytes because Python
+          decided strings should be iterable. Thanks for that footgun.
+    
+    Args:
+        items: Any iterable that may contain nested iterables.
+        
+    Yields:
+        Flattened items from the nested structure.
+        
+    Examples:
+        >>> list(flatten([1, [2, 3], [[4], 5]]))
+        [1, 2, 3, 4, 5]
+        
+        >>> list(flatten(['a', ['b', 'c'], 'd']))
+        ['a', 'b', 'c', 'd']
+        
+        >>> list(flatten([1, [2, [3, [4]]]]))
+        [1, 2, 3, 4]
+        
+        # Without the str check, this would break:
+        >>> list(flatten(['hello', 'world']))
+        ['hello', 'world']  # Not ['h', 'e', 'l', 'l', 'o', 'w', 'o', 'r', 'l', 'd']
+    """
+    for item in items:
+        # The infamous "str is iterable" check we all have to write
+        if isinstance(item, Iterable) and not isinstance(item, (str, bytes)):
+            yield from flatten(item)
+        else:
+            yield item