python-skills 1.0.0__py3-none-any.whl

skills/stdlib/datetime.md

@@ -0,0 +1,187 @@
+# Stdlib: datetime
+
+**Purpose**: Date and time handling with timezone awareness.
+
+**When to use**: All date/time operations. Avoid `time` module for new code.
+
+---
+
+## Core Rules
+
+### Key Types
+```python
+from datetime import datetime, date, time, timedelta, timezone, tzinfo
+
+# date: year, month, day (no time, no tz)
+# time: hour, minute, second, microsecond, tzinfo
+# datetime: date + time + tzinfo
+# timedelta: duration
+# timezone: fixed offset tzinfo
+# ZoneInfo (Python 3.9+): IANA timezone database
+```
+
+### Creation
+```python
+# date
+date(2024, 1, 15)
+date.fromisoformat("2024-01-15")
+date.today()
+
+# time
+time(14, 30, 0)
+time.fromisoformat("14:30:00")
+
+# datetime (naive = no timezone)
+datetime(2024, 1, 15, 14, 30, 0)
+datetime.fromisoformat("2024-01-15T14:30:00")
+datetime.now()          # Local naive
+datetime.utcnow()       # DEPRECATED — avoid
+
+# datetime (aware = with timezone)
+datetime.now(timezone.utc)
+datetime.now(ZoneInfo("America/New_York"))
+datetime.fromisoformat("2024-01-15T14:30:00+00:00")
+```
+
+### Timezone Handling (Critical)
+```python
+from zoneinfo import ZoneInfo  # Python 3.9+
+
+# UTC
+utc = timezone.utc
+dt_utc = datetime.now(utc)
+
+# Named timezone
+ny = ZoneInfo("America/New_York")
+dt_ny = datetime.now(ny)
+
+# Convert between timezones
+dt_ny = dt_utc.astimezone(ny)
+
+# Make naive aware (assume UTC)
+dt_aware = dt_naive.replace(tzinfo=timezone.utc)
+
+# Make aware naive (lose tz info)
+dt_naive = dt_aware.replace(tzinfo=None)
+```
+
+### Operations
+```python
+# Arithmetic
+dt + timedelta(days=7)
+dt - timedelta(hours=3)
+dt1 - dt2  # Returns timedelta
+
+# Comparison (only aware-aware or naive-naive)
+dt1 < dt2
+
+# Replace fields
+dt.replace(year=2025, hour=0)
+
+# Formatting
+dt.isoformat()           # "2024-01-15T14:30:00+00:00"
+dt.strftime("%Y-%m-%d %H:%M:%S")
+dt.strftime("%Y-%m-%dT%H:%M:%S%z")
+
+# Parsing
+datetime.fromisoformat("2024-01-15T14:30:00+00:00")  # Python 3.11+ handles all ISO
+datetime.strptime("15/01/2024", "%d/%m/%Y")
+```
+
+### Timedelta
+```python
+timedelta(days=7, hours=3, minutes=30)
+timedelta(weeks=1)
+timedelta.total_seconds()  # Float seconds
+```
+
+---
+
+## Decision Rules
+
+| Situation | Type |
+|-----------|------|
+| Calendar date only | `date` |
+| Time of day only | `time` |
+| Timestamp (point in time) | `datetime` (aware!) |
+| Duration | `timedelta` |
+| Fixed offset | `timezone(timedelta(hours=5))` |
+| Named timezone | `ZoneInfo("Region/City")` |
+
+---
+
+## Preferred Patterns
+
+```python
+# Always use aware datetimes for timestamps
+def now_utc() -> datetime:
+    return datetime.now(timezone.utc)
+
+# Parse ISO with fallback
+def parse_iso(s: str) -> datetime:
+    try:
+        return datetime.fromisoformat(s)
+    except ValueError:
+        # Handle common variations
+        for fmt in ("%Y-%m-%dT%H:%M:%S%z", "%Y-%m-%dT%H:%M:%S.%f%z", "%Y-%m-%d"):
+            try:
+                return datetime.strptime(s, fmt)
+            except ValueError:
+                continue
+        raise
+
+# Serialize for JSON/API
+def serialize_dt(dt: datetime) -> str:
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.isoformat()
+
+# Deserialize from JSON/API
+def deserialize_dt(s: str) -> datetime:
+    dt = parse_iso(s)
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt
+```
+
+---
+
+## Avoid
+
+- `datetime.utcnow()` (deprecated, returns naive)
+- Naive datetimes for timestamps (ambiguous)
+- `pytz` (use `zoneinfo` stdlib in 3.9+)
+- String manipulation for date math
+- Comparing aware to naive (raises TypeError)
+- `time.mktime` / `time.gmtime` (use datetime methods)
+
+---
+
+## Python 3.11+ Improvements
+
+```python
+# fromisoformat handles all ISO 8601 formats
+datetime.fromisoformat("2024-01-15T14:30:00+05:30")
+datetime.fromisoformat("2024-01-15")  # Returns date, not datetime!
+
+# UTC shortcut
+datetime.UTC  # timezone.utc singleton
+```
+
+---
+
+## Validation Considerations
+
+- Always validate timezone on input
+- Use `isinstance(dt, datetime)` not `type(dt) is datetime`
+- `date` and `datetime` are not comparable
+- `timedelta` has no months/years (variable length)
+
+---
+
+## Related Skills
+
+- `stdlib/json.md` (serialization)
+- `engineering/configuration.md`
+- `security/input_validation.md`
+- `generation/type_hints.md`

skills/stdlib/functools.md

@@ -0,0 +1,238 @@
+# Stdlib: functools
+
+**Purpose**: Higher-order functions and function utilities.
+
+**When to use**: Function composition, caching, decoration, partial application.
+
+---
+
+## Core Rules
+
+### `partial` / `partialmethod`
+```python
+from functools import partial, partialmethod
+
+# Fix arguments
+def power(base, exp):
+    return base ** exp
+
+square = partial(power, exp=2)
+square(5)  # 25
+
+# For methods (binds self)
+class Math:
+    def __init__(self, factor):
+        self.factor = factor
+    def multiply(self, x):
+        return self.factor * x
+    double = partialmethod(multiply, 2)
+```
+
+### `wraps` (Critical for Decorators)
+```python
+from functools import wraps
+
+def my_decorator(func):
+    @wraps(func)  # Copies __name__, __doc__, __annotations__, __module__, __qualname__, __dict__
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs)
+    return wrapper
+```
+
+- **Always** use on decorator wrappers
+- Without it: lost metadata, broken introspection, broken type hints
+
+### `lru_cache` (Memoization)
+```python
+from functools import lru_cache
+
+@lru_cache(maxsize=128)  # None = unbounded
+def fib(n: int) -> int:
+    if n < 2:
+        return n
+    return fib(n-1) + fib(n-2)
+
+fib.cache_info()   # CacheInfo(hits, misses, maxsize, currsize)
+fib.cache_clear()  # Clear cache
+
+# Typed cache (Python 3.9+)
+@lru_cache(maxsize=None, typed=True)
+def typed_func(x: int) -> int:  # Separate cache for int vs float
+    ...
+```
+
+- Thread-safe
+- Only for pure functions (same args → same result)
+- `maxsize` should be power of 2 for performance
+
+### `cache` (Python 3.9+)
+```python
+from functools import cache
+
+@cache
+def expensive(x):
+    ...
+```
+- Unbounded `lru_cache` (no maxsize limit)
+- Simpler for "cache forever" cases
+
+### `cached_property` (Python 3.8+)
+```python
+from functools import cached_property
+
+class DataProcessor:
+    @cached_property
+    def processed(self) -> DataFrame:
+        return expensive_computation(self.raw)
+```
+- Computes once per instance, caches in `__dict__`
+- Not thread-safe for simultaneous first access
+
+### `singledispatch` / `singledispatchmethod`
+```python
+from functools import singledispatch, singledispatchmethod
+
+@singledispatch
+def serialize(obj):
+    raise NotImplementedError(f"Cannot serialize {type(obj)}")
+
+@serialize.register
+def _(obj: int) -> str:
+    return str(obj)
+
+@serialize.register
+def _(obj: list) -> str:
+    return "[" + ", ".join(serialize(x) for x in obj) + "]"
+
+# For methods
+class Formatter:
+    @singledispatchmethod
+    def format(self, value):
+        raise NotImplementedError
+    
+    @format.register
+    def _(self, value: int) -> str:
+        return f"int: {value}"
+```
+
+### `reduce`
+```python
+from functools import reduce
+import operator
+
+reduce(operator.add, [1, 2, 3, 4], 0)   # 10 (with initial)
+reduce(operator.mul, [1, 2, 3, 4])      # 24 (no initial)
+reduce(lambda acc, x: acc + [x*2], items, [])
+```
+
+- Left fold: `reduce(f, [a,b,c], init) = f(f(f(init, a), b), c)`
+- Prefer explicit loops for readability in most cases
+
+### `cmp_to_key`
+```python
+from functools import cmp_to_key
+
+def compare(a, b):
+    return (a > b) - (a < b)  # -1, 0, 1
+
+sorted(items, key=cmp_to_key(compare))
+```
+
+- Convert old-style comparison function to key function
+- Needed for complex sorting not expressible as key
+
+### `total_ordering`
+```python
+from functools import total_ordering
+
+@total_ordering
+class Version:
+    def __init__(self, major, minor, patch):
+        self.tuple = (major, minor, patch)
+    
+    def __eq__(self, other):
+        return self.tuple == other.tuple
+    
+    def __lt__(self, other):
+        return self.tuple < other.tuple
+# Generates __le__, __gt__, __ge__, __ne__
+```
+
+- Define `__eq__` + one of `__lt__`, `__le__`, `__gt__`, `__ge__`
+- Generates the rest
+
+---
+
+## Decision Rules
+
+| Need | Tool |
+|------|------|
+| Fix some arguments | `partial` / `partialmethod` |
+| Cache pure function results | `lru_cache` / `cache` |
+| Cache instance property | `cached_property` |
+| Single-dispatch generic function | `singledispatch` |
+| Single-dispatch method | `singledispatchmethod` |
+| Reduce sequence to single value | `reduce` (or explicit loop) |
+| Old-style comparison to key | `cmp_to_key` |
+| Auto-generate comparisons | `total_ordering` |
+| Preserve decorator metadata | `wraps` (ALWAYS) |
+
+---
+
+## Preferred Patterns
+
+```python
+# Configurable retry with partial
+retry_3 = partial(retry, times=3, delay=1.0)
+retry_5 = partial(retry, times=5, delay=0.5)
+
+# Cached property for expensive computation
+class Service:
+    def __init__(self, config):
+        self.config = config
+    
+    @cached_property
+    def client(self) -> APIClient:
+        return APIClient(self.config.api_key, timeout=self.config.timeout)
+
+# Generic function for extensible serialization
+@singledispatch
+def to_json(obj) -> str:
+    raise TypeError(f"Type {type(obj)} not serializable")
+
+@to_json.register
+def _(obj: datetime) -> str:
+    return obj.isoformat()
+
+@to_json.register
+def _(obj: UUID) -> str:
+    return str(obj)
+```
+
+---
+
+## Avoid
+
+- `lru_cache` on functions with side effects
+- `lru_cache` on methods without `maxsize` (memory leak — instance never freed)
+- `cached_property` with mutable return values (shared reference)
+- `reduce` for simple aggregations (`sum`, `max`, `min`, `any`, `all`)
+- `partial` with mutable default arguments
+- Forgetting `@wraps` on decorators
+
+---
+
+## Validation Considerations
+
+- `cache_info()` for cache effectiveness monitoring
+- `typed=True` prevents `1` and `1.0` sharing cache entry
+- Thread safety: `lru_cache` yes, `cached_property` no
+
+---
+
+## Related Skills
+
+- `core/advanced_python.md` (decorators)
+- `core/functions.md`
+- `generation/async_concurrency.md` (async caching)
+- `quality/functions.md`

skills/stdlib/itertools.md

@@ -0,0 +1,183 @@
+# Stdlib: itertools
+
+**Purpose**: Efficient iteration tools for combinatorics and data processing.
+
+**When to use**: Complex iteration patterns, avoiding manual loops.
+
+---
+
+## Core Rules
+
+### Infinite Iterators
+```python
+import itertools
+
+itertools.count(start=0, step=1)      # 0, 1, 2, ...
+itertools.cycle(iterable)             # Repeat forever
+itertools.repeat(elem, times=None)    # Repeat elem (forever if times=None)
+```
+
+### Finite Iterators (Combinatorics)
+```python
+# Cartesian product
+itertools.product("AB", repeat=2)     # AA, AB, BA, BB
+itertools.product(range(3), "AB")     # (0,A), (0,B), (1,A), ...
+
+# Permutations (order matters)
+itertools.permutations("ABCD", 2)     # AB, AC, AD, BA, BC, BD, CA, CB, CD, DA, DB, DC
+
+# Combinations (order doesn't matter)
+itertools.combinations("ABCD", 2)     # AB, AC, AD, BC, BD, CD
+itertools.combinations_with_replacement("ABCD", 2)  # AA, AB, AC, AD, BB, BC, BD, CC, CD, DD
+```
+
+### Filtering Iterators
+```python
+itertools.filterfalse(pred, iterable)  # Opposite of filter
+itertools.takewhile(pred, iterable)    # Until pred false
+itertools.dropwhile(pred, iterable)    # Skip while pred true
+itertools.compress(data, selectors)    # Data where selector true
+itertools.islice(iterable, start, stop, step)  # Slice iterator
+```
+
+### Grouping
+```python
+# Group consecutive items (input MUST be sorted by key)
+itertools.groupby(iterable, key=lambda x: x[0])
+# Returns (key, group_iterator) — consume group before next iteration!
+
+# Example
+data = [("a", 1), ("a", 2), ("b", 3), ("a", 4)]
+for key, group in itertools.groupby(data, key=lambda x: x[0]):
+    print(key, list(group))
+# a [(a,1), (a,2)]
+# b [(b,3)]
+# a [(a,4)]  # Separate group!
+```
+
+### Accumulation
+```python
+itertools.accumulate(iterable, func=operator.add)
+# Running totals: [1, 2, 3] -> 1, 3, 6
+itertools.accumulate([1,2,3], func=operator.mul)  # 1, 2, 6
+itertools.accumulate([1,2,3], initial=10)         # 10, 11, 13, 16 (Python 3.8+)
+```
+
+### Merging/Transforming
+```python
+itertools.chain(*iterables)              # Flatten: chain(a, b, c)
+itertools.chain.from_iterable(iterable)  # Flatten nested
+itertools.zip_longest(*iterables, fillvalue=None)  # Pad shorter
+itertools.pairwise(iterable)             # (s0,s1), (s1,s2), ... (Python 3.10+)
+itertools.starmap(func, iterable)        # func(*args) for each item
+```
+
+### Recipes (from docs)
+```python
+def batched(iterable, n):
+    "Batch data into tuples of length n. The last batch may be shorter."
+    if n < 1:
+        raise ValueError("n must be at least one")
+    it = iter(iterable)
+    while batch := tuple(itertools.islice(it, n)):
+        yield batch
+
+def sliding_window(iterable, n):
+    "Return a sliding window of width n over the iterable."
+    it = iter(iterable)
+    window = collections.deque(itertools.islice(it, n-1), maxlen=n)
+    for x in it:
+        window.append(x)
+        yield tuple(window)
+
+def roundrobin(*iterables):
+    "roundrobin('ABC', 'D', 'EF') --> A D E B F C"
+    num_active = len(iterables)
+    nexts = cycle(iter(it).__next__ for it in iterables)
+    while num_active:
+        try:
+            for next_func in nexts:
+                yield next_func()
+        except StopIteration:
+            num_active -= 1
+            nexts = cycle(itertools.islice(nexts, num_active))
+```
+
+---
+
+## Decision Rules
+
+| Need | Tool |
+|------|------|
+| All combinations | `product` |
+| Ordered selections | `permutations` |
+| Unordered selections | `combinations` |
+| Unordered with replacement | `combinations_with_replacement` |
+| Skip prefix | `dropwhile` / `islice` |
+| Take prefix | `takewhile` / `islice` |
+| Group consecutive | `groupby` (sort first!) |
+| Running totals | `accumulate` |
+| Flatten sequences | `chain` / `chain.from_iterable` |
+| Parallel iteration with padding | `zip_longest` |
+| Adjacent pairs | `pairwise` (3.10+) |
+| Batch processing | `batched` recipe / `itertools.batched` (3.12+) |
+
+---
+
+## Preferred Patterns
+
+```python
+# Chunk processing
+for batch in batched(large_iterable, 1000):
+    process_batch(batch)
+
+# Pairwise comparison
+for a, b in itertools.pairwise(sorted_data):
+    if b - a > threshold:
+        ...
+
+# Cartesian product for parameter grids
+for params in itertools.product(learning_rates, batch_sizes, optimizers):
+    train(*params)
+
+# Consuming groupby correctly
+for key, group in itertools.groupby(sorted_data, key=keyfunc):
+    group_list = list(group)  # Must consume before next iteration
+    process_group(key, group_list)
+```
+
+---
+
+## Avoid
+
+- `groupby` on unsorted data (produces incorrect groups)
+- Converting large iterators to lists unnecessarily
+- `zip_longest` without considering `fillvalue` semantics
+- Manual index management when `islice`, `enumerate`, `pairwise` exist
+- Nested `product` when single `product` with multiple iterables works
+
+---
+
+## Python 3.12+ Additions
+
+```python
+itertools.batched(iterable, n)  # Built-in batching
+itertools.chunked(iterable, n)  # Alias for batched
+```
+
+---
+
+## Validation Considerations
+
+- All return iterators (lazy)
+- Type checkers understand generic types
+- `groupby` groups are iterators — consume immediately
+
+---
+
+## Related Skills
+
+- `core/data_structures.md`
+- `core/advanced_python.md` (generators)
+- `stdlib/collections.md`
+- `stdlib/functools.md`