oh-my-customcode 0.1.1 → 0.1.3

package/templates/agents/sw-engineer/language/python-expert/refs/python/pep8-style-guide.md

@@ -0,0 +1,202 @@
+# PEP 8 - Style Guide for Python Code
+
+> Source: https://peps.python.org/pep-0008/
+
+## Introduction
+
+This document gives coding conventions for the Python code comprising the standard library. The key insight is that code is read much more often than it is written. Prioritize readability.
+
+## Code Layout
+
+### Indentation
+
+Use 4 spaces per indentation level.
+
+```python
+# Aligned with opening delimiter
+foo = long_function_name(var_one, var_two,
+                         var_three, var_four)
+
+# Hanging indent with additional level
+def long_function_name(
+        var_one, var_two, var_three,
+        var_four):
+    print(var_one)
+```
+
+### Maximum Line Length
+
+- Limit all lines to 79 characters
+- Docstrings/comments: limit to 72 characters
+- Teams may agree on longer lines (up to 99)
+
+### Binary Operators
+
+Break before binary operators:
+
+```python
+# Correct:
+income = (gross_wages
+          + taxable_interest
+          + (dividends - qualified_dividends))
+```
+
+### Blank Lines
+
+- Two blank lines around top-level definitions
+- One blank line between method definitions
+- Extra blank lines sparingly to separate logical sections
+
+## Imports
+
+```python
+# Standard library
+import os
+import sys
+
+# Third party
+import numpy as np
+
+# Local
+from myproject import mymodule
+```
+
+Rules:
+- One import per line
+- Absolute imports preferred
+- Avoid wildcard imports
+
+## Whitespace
+
+```python
+# Correct:
+spam(ham[1], {eggs: 2})
+x = 1
+y = 2
+long_variable = 3
+
+# Wrong:
+spam( ham[ 1 ], { eggs: 2 } )
+x             = 1
+y             = 2
+long_variable = 3
+```
+
+## Comments
+
+### Block Comments
+
+```python
+# This is a block comment that
+# spans multiple lines and describes
+# the following code block.
+```
+
+### Inline Comments
+
+```python
+x = x + 1  # Increment x
+```
+
+### Docstrings
+
+```python
+def complex(real=0.0, imag=0.0):
+    """Form a complex number.
+
+    Keyword arguments:
+    real -- the real part (default 0.0)
+    imag -- the imaginary part (default 0.0)
+    """
+    pass
+```
+
+## Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Module | lowercase_underscore | `my_module` |
+| Package | lowercase | `mypackage` |
+| Class | CapWords | `MyClass` |
+| Exception | CapWords + Error | `CustomError` |
+| Function | lowercase_underscore | `my_function` |
+| Variable | lowercase_underscore | `my_var` |
+| Constant | UPPER_UNDERSCORE | `MAX_SIZE` |
+| Method | lowercase_underscore | `my_method` |
+
+### Special Naming
+
+- `_single_leading`: weak "internal use" indicator
+- `__double_leading`: name mangling in classes
+- `__double_both__`: "magic" methods
+
+## Programming Recommendations
+
+### Comparisons
+
+```python
+# Correct:
+if foo is not None:
+if isinstance(obj, int):
+
+# Wrong:
+if foo != None:
+if type(obj) is int:
+```
+
+### Sequences
+
+```python
+# Correct:
+if not seq:
+if seq:
+
+# Wrong:
+if len(seq) == 0:
+if len(seq) > 0:
+```
+
+### Exception Handling
+
+```python
+# Correct:
+try:
+    value = collection[key]
+except KeyError:
+    return key_not_found(key)
+
+# Wrong:
+try:
+    value = collection[key]
+except:  # Bare except
+    return key_not_found(key)
+```
+
+### Context Managers
+
+```python
+# Correct:
+with open('file.txt') as f:
+    contents = f.read()
+
+# Wrong:
+f = open('file.txt')
+contents = f.read()
+f.close()
+```
+
+### Return Statements
+
+```python
+# Correct:
+def foo(x):
+    if x >= 0:
+        return math.sqrt(x)
+    else:
+        return None
+
+# Wrong:
+def foo(x):
+    if x >= 0:
+        return math.sqrt(x)
+```

package/templates/agents/sw-engineer/language/python-expert/refs/python/zen-of-python.md

@@ -0,0 +1,79 @@
+# The Zen of Python (PEP 20)
+
+> Source: https://peps.python.org/pep-0020/
+
+Long time Pythoneer Tim Peters succinctly channels the BDFL's guiding principles for Python's design into 20 aphorisms, only 19 of which have been written down.
+
+```
+>>> import this
+```
+
+## The 19 Aphorisms
+
+1. **Beautiful is better than ugly.**
+   - Write elegant, readable code
+
+2. **Explicit is better than implicit.**
+   - Don't hide behavior; make intentions clear
+
+3. **Simple is better than complex.**
+   - Choose straightforward solutions
+
+4. **Complex is better than complicated.**
+   - When complexity is needed, keep it manageable
+
+5. **Flat is better than nested.**
+   - Avoid deep nesting; keep structures flat
+
+6. **Sparse is better than dense.**
+   - Don't pack too much into one line
+
+7. **Readability counts.**
+   - Code is read more often than written
+
+8. **Special cases aren't special enough to break the rules.**
+   - Consistency matters
+
+9. **Although practicality beats purity.**
+   - Be pragmatic when needed
+
+10. **Errors should never pass silently.**
+    - Handle or propagate errors explicitly
+
+11. **Unless explicitly silenced.**
+    - Intentional suppression is acceptable
+
+12. **In the face of ambiguity, refuse the temptation to guess.**
+    - Ask for clarification; don't assume
+
+13. **There should be one-- and preferably only one --obvious way to do it.**
+    - Python favors one canonical approach
+
+14. **Although that way may not be obvious at first unless you're Dutch.**
+    - (A nod to Guido van Rossum)
+
+15. **Now is better than never.**
+    - Don't over-plan; start implementing
+
+16. **Although never is often better than *right* now.**
+    - But don't rush without thought
+
+17. **If the implementation is hard to explain, it's a bad idea.**
+    - Complexity is a warning sign
+
+18. **If the implementation is easy to explain, it may be a good idea.**
+    - Simplicity suggests good design
+
+19. **Namespaces are one honking great idea -- let's do more of those!**
+    - Organize code into clear namespaces
+
+## Application
+
+When writing Python code, ask yourself:
+- Is this beautiful or ugly?
+- Is this explicit or implicit?
+- Is this simple or complex?
+- Is this readable?
+- Could I easily explain this to someone else?
+
+The Zen of Python is not just style guidance—it's a philosophy for writing maintainable, understandable code.

package/templates/agents/sw-engineer/language/python-expert/refs/python-best-practices/SKILL.md

@@ -0,0 +1,221 @@
+# Python Best Practices Skill
+
+> **Category**: Development
+> **Source**: Internal (based on PEP 8 and PEP 20)
+
+## Purpose
+
+Apply idiomatic Python patterns and best practices from official Python documentation.
+
+## The Zen of Python (PEP 20)
+
+```
+Beautiful is better than ugly.
+Explicit is better than implicit.
+Simple is better than complex.
+Complex is better than complicated.
+Flat is better than nested.
+Sparse is better than dense.
+Readability counts.
+Special cases aren't special enough to break the rules.
+Although practicality beats purity.
+Errors should never pass silently.
+Unless explicitly silenced.
+In the face of ambiguity, refuse the temptation to guess.
+There should be one-- and preferably only one --obvious way to do it.
+Although that way may not be obvious at first unless you're Dutch.
+Now is better than never.
+Although never is often better than *right* now.
+If the implementation is hard to explain, it's a bad idea.
+If the implementation is easy to explain, it may be a good idea.
+Namespaces are one honking great idea -- let's do more of those!
+```
+
+## Rules
+
+### 1. Code Layout
+
+```yaml
+indentation:
+  - Use 4 spaces per indentation level
+  - Never mix tabs and spaces
+  - Continuation lines align vertically or use hanging indent
+
+line_length:
+  - Maximum 79 characters for code
+  - Maximum 72 characters for docstrings/comments
+  - Teams may agree on 99 characters for code
+
+blank_lines:
+  - Two blank lines around top-level definitions
+  - One blank line between method definitions
+  - Use sparingly inside functions
+```
+
+### 2. Imports
+
+```yaml
+rules:
+  - One import per line
+  - Position at file top, after docstrings
+  - Group order: standard library → third-party → local
+  - Separate groups with blank lines
+  - Prefer absolute imports
+  - Avoid wildcard imports (from X import *)
+
+example: |
+  import os
+  import sys
+
+  from third_party import lib
+
+  from myproject import module
+```
+
+### 3. Whitespace
+
+```yaml
+avoid:
+  - Extra spaces inside parentheses/brackets
+  - Spaces before commas or colons
+  - Spaces between function name and parenthesis
+  - Multiple spaces for alignment
+
+required:
+  - Single space around binary operators
+  - Spaces around -> in annotations
+  - No spaces around = for default parameters
+```
+
+### 4. Naming Conventions
+
+```yaml
+modules_packages:
+  style: lowercase_with_underscores
+  example: my_module
+
+classes:
+  style: CapWords
+  example: MyClass
+
+functions_variables:
+  style: lowercase_with_underscores
+  example: my_function, my_variable
+
+constants:
+  style: ALL_CAPS_WITH_UNDERSCORES
+  example: MAX_SIZE, DEFAULT_VALUE
+
+exceptions:
+  style: CapWords + Error suffix
+  example: ValueError, CustomError
+
+private:
+  single_underscore: _internal (weak internal)
+  double_underscore: __private (name mangling)
+  trailing_underscore: class_ (avoid keyword conflict)
+
+avoid:
+  - Single characters l, O, I (ambiguous)
+```
+
+### 5. Comments and Docstrings
+
+```yaml
+principles:
+  - Comments contradicting code are worse than none
+  - Use complete sentences
+  - Keep comments up to date
+
+block_comments:
+  - Indent at same level as code
+  - Start each line with # and space
+
+inline_comments:
+  - Minimum two spaces from code
+  - Avoid obvious statements
+
+docstrings:
+  - Write for all public modules, functions, classes, methods
+  - Use triple quotes
+  - First line: concise summary
+  - Blank line before detailed description
+```
+
+### 6. Programming Recommendations
+
+```yaml
+comparisons:
+  - Use 'is' and 'is not' for None, True, False
+  - Prefer isinstance() over type()
+  - Use 'is not' rather than 'not ... is'
+
+sequences:
+  - Test empty: if not seq: (not if len(seq) == 0)
+  - Use .startswith() and .endswith()
+
+exceptions:
+  - Derive from Exception, not BaseException
+  - Catch specific exceptions
+  - Avoid bare except clauses
+  - Use 'raise X from Y' for chaining
+
+functions:
+  - Use def, not lambda assignment
+  - Consistent return statements
+  - Use with for resource management
+
+type_hints:
+  - Follow PEP 484 syntax
+  - Space after colon in annotations
+  - No space before colon
+```
+
+### 7. Pythonic Idioms
+
+```yaml
+list_comprehension:
+  prefer: "[x*2 for x in items if x > 0]"
+  over: |
+    result = []
+    for x in items:
+        if x > 0:
+            result.append(x*2)
+
+context_managers:
+  prefer: "with open('file') as f:"
+  over: |
+    f = open('file')
+    try:
+        ...
+    finally:
+        f.close()
+
+unpacking:
+  prefer: "a, b = b, a"
+  over: |
+    temp = a
+    a = b
+    b = temp
+
+enumerate:
+  prefer: "for i, item in enumerate(items):"
+  over: "for i in range(len(items)):"
+
+dictionary:
+  prefer: "d.get(key, default)"
+  over: "d[key] if key in d else default"
+```
+
+## Application
+
+When writing or reviewing Python code:
+
+1. **Always** follow PEP 8 formatting
+2. **Always** write docstrings for public APIs
+3. **Prefer** explicit over implicit
+4. **Prefer** simple over complex
+5. **Prefer** flat over nested
+6. **Avoid** premature optimization
+7. **Use** list comprehensions when readable
+8. **Use** context managers for resources

package/templates/agents/sw-engineer/language/python-expert/refs/python-best-practices/index.yaml

@@ -0,0 +1,25 @@
+# Python Best Practices Skill
+
+metadata:
+  name: python-best-practices
+  category: development
+  description: Pythonic patterns from PEP 8 and PEP 20
+
+source:
+  type: internal
+  reference:
+    - https://peps.python.org/pep-0008/
+    - https://peps.python.org/pep-0020/
+    - https://google.github.io/styleguide/pyguide.html
+
+provides:
+  - Python code formatting standards
+  - Naming conventions
+  - Import organization
+  - Whitespace rules
+  - Comment and docstring guidelines
+  - Programming recommendations
+  - Pythonic idioms
+
+used_by:
+  - python-expert