symbex 1.2__py3-none-any.whl → 1.3.1__py3-none-any.whl

symbex/cli.py

@@ -120,6 +120,21 @@ from .lib import (
     is_flag=True,
     help="Filter functions without docstrings",
 )
+@click.option(
+    "--public",
+    is_flag=True,
+    help="Filter for symbols without a _ prefix",
+)
+@click.option(
+    "--private",
+    is_flag=True,
+    help="Filter for symbols with a _ prefix",
+)
+@click.option(
+    "--dunder",
+    is_flag=True,
+    help="Filter for symbols matching __*__",
+)
 @click.option(
     "--typed",
     is_flag=True,
@@ -174,6 +189,9 @@ def cli(
     class_,
     documented,
     undocumented,
+    public,
+    private,
+    dunder,
     typed,
     untyped,
     partially_typed,
@@ -234,6 +252,11 @@ def cli(
             # This is a replacement implementation
             return a + b + 3
         " | symbex my_function --replace
+
+    \b
+        # Replace my_function with the output of a command:
+        symbex first_function --rexec "sed 's/^/# /'"
+        # This uses sed to comment out the function body
     """
     if modules:
         module_dirs = []
@@ -281,6 +304,9 @@ def cli(
             class_,
             documented,
             undocumented,
+            public,
+            private,
+            dunder,
             typed,
             untyped,
             partially_typed,
@@ -312,6 +338,9 @@ def cli(
                 class_,
                 documented,
                 undocumented,
+                public,
+                private,
+                dunder,
                 typed,
                 untyped,
                 partially_typed,
@@ -347,6 +376,9 @@ def cli(
             class_,
             documented,
             undocumented,
+            public,
+            private,
+            dunder,
             typed,
             untyped,
             partially_typed,
@@ -371,6 +403,12 @@ def cli(
                 return False
             if undocumented and ast.get_docstring(node):
                 return False
+            if public and node.name.startswith("_") and not is_dunder(node.name):
+                return False
+            if private and (is_dunder(node.name) or not node.name.startswith("_")):
+                return False
+            if dunder and not is_dunder(node.name):
+                return False
             summary = type_summary(node)
             # if no summary, type filters all fail
             if not summary and (
@@ -499,3 +537,7 @@ def is_subpath(path: pathlib.Path, parent: pathlib.Path) -> bool:
         return True
     except ValueError:
         return False
+
+
+def is_dunder(name):
+    return name.startswith("__") and name.endswith("__")

symbex/lib.py

@@ -169,7 +169,7 @@ def function_definition(function_node: AST):
     if isinstance(function_node, AsyncFunctionDef):
         def_ = "async def "
 
-    return f"{def_}{function_name}({arguments_str}){return_annotation}"
+    return f"{def_}{function_name}({arguments_str}){return_annotation}:"
 
 
 def class_definition(class_def):
@@ -201,7 +201,7 @@ def class_definition(class_def):
     if signature:
         signature = f"({signature})"
 
-    class_definition = f"class {class_def.name}{signature}"
+    class_definition = f"class {class_def.name}{signature}:"
 
     return class_definition
 

{symbex-1.2.dist-info → symbex-1.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: symbex
-Version: 1.2
+Version: 1.3.1
 Summary: Find the Python code for specified symbols
 Home-page: https://github.com/simonw/symbex
 Author: Simon Willison
@@ -121,6 +121,9 @@ The following filters are available:
 - `--unasync` - only non-async functions
 - `--documented` - functions/classes that have a docstring
 - `--undocumented` - functions/classes that do not have a docstring
+- `--public` - functions/classes that are public - don't have a `_name` prefix (or are `__*__` methods)
+- `--private` - functions/classes that are private - have a `_name` prefix and are not `__*__`
+- `--dunder` - functions matching `__*__` - this should usually be used with `*.*` to find all dunder methods
 - `--typed` - functions that have at least one type annotation
 - `--untyped` - functions that have no type annotations
 - `--partially-typed` - functions that have some type annotations but not all
@@ -141,6 +144,12 @@ This example shows the full source code of every class method in the Python stan
 symbex --fully-typed --no-init '*.*' --stdlib
 ```
 
+To find all public functions and methods that lack documentation, just showing the signature of each one:
+
+```bash
+symbex '*' '*.*' --public --undocumented --signatures
+```
+
 ### Example output
 
 In a fresh checkout of [Datasette](https://github.com/simonw/datasette) I ran this command:
@@ -196,40 +205,40 @@ cog.out(
 ]]] -->
 ```python
 # File: symbex/lib.py Line: 107
-def function_definition(function_node: AST)
+def function_definition(function_node: AST):
 
 # File: symbex/lib.py Line: 13
-def find_symbol_nodes(code: str, filename: str, symbols: Iterable[str]) -> List[Tuple[(AST, Optional[str])]]
+def find_symbol_nodes(code: str, filename: str, symbols: Iterable[str]) -> List[Tuple[(AST, Optional[str])]]:
 
 # File: symbex/lib.py Line: 175
-def class_definition(class_def)
+def class_definition(class_def):
 
 # File: symbex/lib.py Line: 209
-def annotation_definition(annotation: AST) -> str
+def annotation_definition(annotation: AST) -> str:
 
 # File: symbex/lib.py Line: 227
-def read_file(path)
+def read_file(path):
 
 # File: symbex/lib.py Line: 253
-class TypeSummary
+class TypeSummary:
 
 # File: symbex/lib.py Line: 258
-def type_summary(node: AST) -> Optional[TypeSummary]
+def type_summary(node: AST) -> Optional[TypeSummary]:
 
 # File: symbex/lib.py Line: 304
-def quoted_string(s)
+def quoted_string(s):
 
 # File: symbex/lib.py Line: 315
-def import_line_for_function(function_name: str, filepath: str, possible_root_dirs: List[str]) -> str
+def import_line_for_function(function_name: str, filepath: str, possible_root_dirs: List[str]) -> str:
 
 # File: symbex/lib.py Line: 37
-def code_for_node(code: str, node: AST, class_name: str, signatures: bool, docstrings: bool) -> Tuple[(str, int)]
+def code_for_node(code: str, node: AST, class_name: str, signatures: bool, docstrings: bool) -> Tuple[(str, int)]:
 
 # File: symbex/lib.py Line: 71
-def add_docstring(definition: str, node: AST, docstrings: bool, is_method: bool) -> str
+def add_docstring(definition: str, node: AST, docstrings: bool, is_method: bool) -> str:
 
 # File: symbex/lib.py Line: 82
-def match(name: str, symbols: Iterable[str]) -> bool
+def match(name: str, symbols: Iterable[str]) -> bool:
 ```
 <!-- [[[end]]] -->
 This can be combined with other options, or you can run `symbex -s` to see every symbol in the current directory and its subdirectories.
@@ -251,7 +260,7 @@ cog.out(
 ```python
 # File: symbex/lib.py Line: 82
 # from symbex.lib import match
-def match(name: str, symbols: Iterable[str]) -> bool
+def match(name: str, symbols: Iterable[str]) -> bool:
 ```
 <!-- [[[end]]] -->
 To suppress the `# File: ...` comments, use `--no-file` or `-n`.
@@ -271,7 +280,7 @@ cog.out(
 ]]] -->
 ```python
 # from symbex.lib import match
-def match(name: str, symbols: Iterable[str]) -> bool
+def match(name: str, symbols: Iterable[str]) -> bool:
 ```
 <!-- [[[end]]] -->
 
@@ -288,7 +297,7 @@ cog.out(
 ]]] -->
 ```python
 # File: symbex/lib.py Line: 82
-def match(name: str, symbols: Iterable[str]) -> bool
+def match(name: str, symbols: Iterable[str]) -> bool:
     "Returns True if name matches any of the symbols, resolving wildcards"
 ```
 <!-- [[[end]]] -->
@@ -405,14 +414,24 @@ def second_function(a: int, b: int) -> int:
 
 The `--check` option causes `symbex` to return a non-zero exit code if any matches are found for your query.
 
-You can use this in CI to guard against things like functions being added without documentation:
+You can use this in CI to guard against things like public functions being added without documentation:
 
 ```bash
-symbex --function --undocumented --check
+symbex --function --public --undocumented --check
 ```
 This will fail silently but set a `1` exit code if there are any undocumented functions.
 
-`--check` will not output anything by default. Add `--count` to output a count of matching symbols, or `-s/--signatures` to output the signatures of the matching symbols.
+Using this as a step in a CI tool such as GitHub Actions should result in a test failure.
+
+Run this to see the exit code from the last command:
+```bash
+echo $?
+```
+
+`--check` will not output anything by default. Add `--count` to output a count of matching symbols, or `-s/--signatures` to output the signatures of the matching symbols, for example:
+```bash
+symbex --function --public --undocumented --check --count
+```
 
 ## Similar tools
 
@@ -471,6 +490,10 @@ Usage: symbex [OPTIONS] [SYMBOLS]...
           return a + b + 3
       " | symbex my_function --replace
 
+      # Replace my_function with the output of a command:
+      symbex first_function --rexec "sed 's/^/# /'"
+      # This uses sed to comment out the function body
+
 Options:
   --version                  Show the version and exit.
   -f, --file FILE            Files to search
@@ -491,6 +514,9 @@ Options:
   --class                    Filter classes
   --documented               Filter functions with docstrings
   --undocumented             Filter functions without docstrings
+  --public                   Filter for symbols without a _ prefix
+  --private                  Filter for symbols with a _ prefix
+  --dunder                   Filter for symbols matching __*__
   --typed                    Filter functions with type annotations
   --untyped                  Filter functions without type annotations
   --partially-typed          Filter functions with partial type annotations

symbex-1.3.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+symbex/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+symbex/__main__.py,sha256=8hDtWlaFZK24KhfNq_ZKgtXqYHsDQDetukOCMlsbW0Q,59
+symbex/cli.py,sha256=uuP28l7qAWWPE3b0u2HLM1ID89m402EBNgYOhcejdgw,14974
+symbex/lib.py,sha256=CiKKOOyc6Ne_7igzNItMZpa5I6o12LEbIPrQU9al7Ro,11436
+symbex-1.3.1.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+symbex-1.3.1.dist-info/METADATA,sha256=1oJBLr7_LdzFltBb5cMMCttPFo-XZhFGOzK_1MOQ9ls,19263
+symbex-1.3.1.dist-info/WHEEL,sha256=yQN5g4mg4AybRjkgi-9yy4iQEFibGQmlz78Pik5Or-A,92
+symbex-1.3.1.dist-info/entry_points.txt,sha256=YgMSEfEGqNMHM9RysFObH8lkQKVZKyymKLnXbVue_Uk,42
+symbex-1.3.1.dist-info/top_level.txt,sha256=qwle8HjAaYgpdMIHlJcTcN4gaG4wmDqUvkt54beTBTs,7
+symbex-1.3.1.dist-info/RECORD,,

{symbex-1.2.dist-info → symbex-1.3.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.40.0)
+Generator: bdist_wheel (0.41.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

symbex-1.2.dist-info/RECORD

@@ -1,10 +0,0 @@
-symbex/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-symbex/__main__.py,sha256=8hDtWlaFZK24KhfNq_ZKgtXqYHsDQDetukOCMlsbW0Q,59
-symbex/cli.py,sha256=6jts3COuZSwfK_HbEtptUs5IRC7VP5woGQHJTkm_CFk,13881
-symbex/lib.py,sha256=xgn-tiLoeIvu2iYpwuB7fvDK6epBBd5VHSc2Y7wRQsk,11434
-symbex-1.2.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-symbex-1.2.dist-info/METADATA,sha256=v2zGtiB2GYz7Tc23UJiPvcK_AUFGJuSztikZiMvVFPE,18139
-symbex-1.2.dist-info/WHEEL,sha256=pkctZYzUS4AYVn6dJ-7367OJZivF2e8RA9b_ZBjif18,92
-symbex-1.2.dist-info/entry_points.txt,sha256=YgMSEfEGqNMHM9RysFObH8lkQKVZKyymKLnXbVue_Uk,42
-symbex-1.2.dist-info/top_level.txt,sha256=qwle8HjAaYgpdMIHlJcTcN4gaG4wmDqUvkt54beTBTs,7
-symbex-1.2.dist-info/RECORD,,