diff --git a/src/codegen/git/models/pr_options.py b/src/codegen/git/models/pr_options.py index 041fff764..345518ff9 100644 --- a/src/codegen/git/models/pr_options.py +++ b/src/codegen/git/models/pr_options.py @@ -5,7 +5,14 @@ @apidoc class PROptions(BaseModel): - """Options for generating a PR.""" + """Options for generating a PR. + + Attributes: + title: The title of the pull request. + body: The body content of the pull request. + labels: A list of labels to be added to the pull request. + force_push_head_branch: Whether to force push the head branch. + """ title: str | None = None body: str | None = None diff --git a/src/codegen/sdk/code_generation/doc_utils/generate_docs_json.py b/src/codegen/sdk/code_generation/doc_utils/generate_docs_json.py index c2f332f6a..12804fd50 100644 --- a/src/codegen/sdk/code_generation/doc_utils/generate_docs_json.py +++ b/src/codegen/sdk/code_generation/doc_utils/generate_docs_json.py @@ -9,10 +9,25 @@ from codegen.sdk.core.codebase import Codebase from codegen.sdk.core.placeholder.placeholder_type import TypePlaceholder -ATTRIBUTES_TO_IGNORE = ["G", "node_id", "angular"] - - -def generate_docs_json(codebase: Codebase, head_commit: str) -> dict[str, dict[str, Any]]: +ATTRIBUTES_TO_IGNORE = [ + "G", + "node_id", + "angular", + "model_config", + "constructor_keyword", + "viz", + "console", + "items", + "node_type", + "ts_node", + "file_node_id", + "G", + "statement_type", + "assignment_types", +] + + +def generate_docs_json(codebase: Codebase, head_commit: str, raise_on_missing_docstring: bool = False) -> dict[str, dict[str, Any]]: """Update documentation table for classes, methods and attributes in the codebase. Args: @@ -23,7 +38,6 @@ def generate_docs_json(codebase: Codebase, head_commit: str) -> dict[str, dict[s """ codegen_sdk_docs = GSDocs(classes=[]) types_cache = {} - attr_cache = {} def process_class_doc(cls): """Update or create documentation for a class.""" @@ -110,22 +124,22 @@ def process_attribute(attr, cls, cls_doc, seen_methods): return attr_path = create_path(attr, cls) - original_attr_path = create_path(attr) - if original_attr_path not in attr_cache: - description = attr.docstring(cls) - attr_return_type = [] - if r_type := get_type_str(attr): - if isinstance(r_type, TypePlaceholder): - resolved_types = [] - else: - resolved_types = r_type.resolved_types - r_type_source = replace_multiple_types(codebase=codebase, input_str=r_type.source, resolved_types=resolved_types, parent_class=cls, parent_symbol=attr, types_cache=types_cache) - attr_return_type.append(r_type_source) + description = attr.docstring(attr.parent_class) + if raise_on_missing_docstring and not description: + msg = f"Attribute {attr.parent_class.name}.{attr.name} does not have a docstring" + raise ValueError(msg) + attr_return_type = [] + if r_type := get_type_str(attr): + if isinstance(r_type, TypePlaceholder): + resolved_types = [] + else: + resolved_types = r_type.resolved_types + r_type_source = replace_multiple_types(codebase=codebase, input_str=r_type.source, resolved_types=resolved_types, parent_class=cls, parent_symbol=attr, types_cache=types_cache) + attr_return_type.append(r_type_source) - attr_cache[original_attr_path] = {"description": description, "attr_return_type": attr_return_type} + attr_info = {"description": description, "attr_return_type": attr_return_type} - attr_info = attr_cache[original_attr_path] meta_data = {"parent": create_path(attr.parent_class), "path": attr.file.filepath} return MethodDoc( diff --git a/src/codegen/sdk/codebase/span.py b/src/codegen/sdk/codebase/span.py index d8e7375cb..d7933927e 100644 --- a/src/codegen/sdk/codebase/span.py +++ b/src/codegen/sdk/codebase/span.py @@ -54,7 +54,12 @@ def range_json_schema() -> JsonSchemaValue: @apidoc class Span(BaseModel): - """Range within the codebase""" + """Range within the codebase + + Attributes: + range: Adapter for the range within the codebase. + filepath: The path to the file associated with the range. + """ model_config = ConfigDict( frozen=True, diff --git a/src/codegen/sdk/core/assignment.py b/src/codegen/sdk/core/assignment.py index 3f09e1050..cb0339307 100644 --- a/src/codegen/sdk/core/assignment.py +++ b/src/codegen/sdk/core/assignment.py @@ -45,15 +45,14 @@ class Assignment(Symbol[Parent, ...], Typeable[Parent, ...], HasValue, Generic[Parent]): """Represents an assignment for a single variable within an assignment statement. - Attributes: - left: The left side of the assignment - right: The right side of the assignment - Example: ```typescript var z var z = 5 ``` + + Attributes: + symbol_type: The type of symbol, set to SymbolType.GlobalVar. """ _left: Expression[Self] diff --git a/src/codegen/sdk/core/class_definition.py b/src/codegen/sdk/core/class_definition.py index 9fe1c207b..785f0e20e 100644 --- a/src/codegen/sdk/core/class_definition.py +++ b/src/codegen/sdk/core/class_definition.py @@ -51,7 +51,13 @@ @apidoc class Class(Inherits[TType], HasBlock[TCodeBlock, TDecorator], Callable[TParameter, TType], HasAttribute[TFunction | Attribute], Generic[TFunction, TDecorator, TCodeBlock, TParameter, TType]): - """Abstract representation of a Class definition.""" + """Abstract representation of a Class definition. + + Attributes: + symbol_type: The type of symbol, set to SymbolType.Class. + constructor_keyword: The keyword used to identify the constructor method. + parent_classes: The parent classes of this class, if any. + """ symbol_type = SymbolType.Class constructor_keyword = None diff --git a/src/codegen/sdk/core/codebase.py b/src/codegen/sdk/core/codebase.py index ee14c9f99..cee8f58a0 100644 --- a/src/codegen/sdk/core/codebase.py +++ b/src/codegen/sdk/core/codebase.py @@ -106,7 +106,10 @@ class Codebase(Generic[TSourceFile, TDirectory, TSymbol, TClass, TFunction, TImport, TGlobalVar, TInterface, TTypeAlias, TParameter, TCodeBlock]): """This class provides the main entrypoint for most programs to analyzing and manipulating codebases. - It provides a high-level interface to interact with the codebase graph, and provides methods to access and manipulate files, directories, symbols, and other entities in the codebase. + Attributes: + viz: Manages visualization of the codebase graph. + repo_path: The path to the repository. + console: Manages console output for the codebase. """ _op: RepoOperator | RemoteRepoOperator diff --git a/src/codegen/sdk/core/dataclasses/usage.py b/src/codegen/sdk/core/dataclasses/usage.py index 3cb9f618e..60c44a196 100644 --- a/src/codegen/sdk/core/dataclasses/usage.py +++ b/src/codegen/sdk/core/dataclasses/usage.py @@ -27,6 +27,7 @@ class Usage: Attributes: match: The exact match of the usage usage_symbol: The symbol this object is used in + imported_by: The import statement that brought this symbol into scope, or None if not imported usage_type: How this symbol was used kind: Where this symbol was used (IE: in a type parameter or in the body of the class, etc) """ @@ -62,15 +63,17 @@ class UsageKind(IntEnum): Attributes: SUBCLASS: Used in symbol inheritance. - TYPE_ANNOTATION: Used as a type annotation on a parameter or assignment statement. + TYPED_PARAMETER: Used as a typed parameter in a function/method. + TYPE_ANNOTATION: Used as a type annotation on a parameter or assignment statement. BODY: Usage within the body of a function/method. DECORATOR: Usage within a decorator. - RETURN_TYPE: Used as a return type annotation + RETURN_TYPE: Used as a return type annotation. TYPE_DEFINITION: Used in a type alias. EXPORTED_SYMBOL: Used in an export statement. EXPORTED_WILDCARD: Re-exported by a wildcard export. GENERIC: Used as a type parameter to another type. IMPORTED: Imported with an import statement. + IMPORTED_WILDCARD: Imported with a wildcard import statement. DEFAULT_VALUE: Represents a default value in a function/method parameter. """ diff --git a/src/codegen/sdk/core/detached_symbols/code_block.py b/src/codegen/sdk/core/detached_symbols/code_block.py index dff0144ab..c267d328c 100644 --- a/src/codegen/sdk/core/detached_symbols/code_block.py +++ b/src/codegen/sdk/core/detached_symbols/code_block.py @@ -45,6 +45,10 @@ class CodeBlock(Expression[Parent], Generic[Parent, TAssignment]): function body or class body. Enables various types of queries and operations on the code block. + + Attributes: + level: The indentation level of the code block. + parent_block: The parent code block containing this block, or None if it is a top-level block. """ level: int diff --git a/src/codegen/sdk/core/directory.py b/src/codegen/sdk/core/directory.py index 0254b6af8..fcbf8711a 100644 --- a/src/codegen/sdk/core/directory.py +++ b/src/codegen/sdk/core/directory.py @@ -39,7 +39,14 @@ @apidoc class Directory(Generic[TFile, TSymbol, TImportStatement, TGlobalVar, TClass, TFunction, TImport]): """Directory representation for codebase. + GraphSitter abstraction of a file directory that can be used to look for files and symbols within a specific directory. + + Attributes: + path: Absolute path of the directory. + dirpath: Relative path of the directory. + parent: The parent directory, if any. + items: A dictionary containing files and subdirectories within the directory. """ path: Path # Absolute Path diff --git a/src/codegen/sdk/core/export.py b/src/codegen/sdk/core/export.py index 4a9eeb1c4..3c419a2ef 100644 --- a/src/codegen/sdk/core/export.py +++ b/src/codegen/sdk/core/export.py @@ -21,7 +21,11 @@ @apidoc class Export(Exportable[Parent], Generic[Parent]): - """Represents a single symbol being exported.""" + """Represents a single symbol being exported. + + Attributes: + export_statement: The statement representing the export. + """ export_statement: ExportStatement diff --git a/src/codegen/sdk/core/expressions/binary_expression.py b/src/codegen/sdk/core/expressions/binary_expression.py index cda883a5b..24554845a 100644 --- a/src/codegen/sdk/core/expressions/binary_expression.py +++ b/src/codegen/sdk/core/expressions/binary_expression.py @@ -23,7 +23,12 @@ @apidoc class BinaryExpression(Expression[Parent], Chainable, Generic[Parent]): - """Represents binary expressions, e.g. all of +,-,*,/, as well as booleaneoperations (and, or) etc.""" + """Represents binary expressions, e.g. all of +,-,*,/, as well as boolean operations (and, or) etc. + + Attributes: + left: The left operand of the binary expression. + right: The right operand of the binary expression. + """ left: Expression[Self] | None right: Expression[Self] | None diff --git a/src/codegen/sdk/core/expressions/expression.py b/src/codegen/sdk/core/expressions/expression.py index 3ecdf5bd1..85cc5d794 100644 --- a/src/codegen/sdk/core/expressions/expression.py +++ b/src/codegen/sdk/core/expressions/expression.py @@ -13,7 +13,11 @@ @apidoc class Expression(Editable[Parent], Generic[Parent]): - """Represents an arbitrary Expression, such as List, Dict, Binary Expression, String.""" + """Represents an arbitrary Expression, such as List, Dict, Binary Expression, String. + + Attributes: + node_type: The type of the node, set to NodeType.EXPRESSION. + """ node_type: NodeType = NodeType.EXPRESSION diff --git a/src/codegen/sdk/core/expressions/multi_expression.py b/src/codegen/sdk/core/expressions/multi_expression.py index fb65ffa94..58bfa8ccc 100644 --- a/src/codegen/sdk/core/expressions/multi_expression.py +++ b/src/codegen/sdk/core/expressions/multi_expression.py @@ -21,7 +21,11 @@ @apidoc class MultiExpression(Expression[Parent], Generic[Parent, TExpression]): - """Represents an group of Expressions, such as List, Dict, Binary Expression, String.""" + """Represents an group of Expressions, such as List, Dict, Binary Expression, String. + + Attributes: + expressions: A list of expressions contained within the MultiExpression. + """ expressions: list[TExpression] diff --git a/src/codegen/sdk/core/expressions/string.py b/src/codegen/sdk/core/expressions/string.py index 4101a3bf8..b604e4486 100644 --- a/src/codegen/sdk/core/expressions/string.py +++ b/src/codegen/sdk/core/expressions/string.py @@ -26,7 +26,8 @@ class String(Expression[Parent], Builtin, Generic[Parent]): Attributes: content: The content of the string - expressions: embedded expressions in the string, only applicable for templated or formatted strings + content_nodes: A collection of string fragments and escape sequences in TS, or a single string content in Python. + expressions: Embedded expressions in the string, only applicable for templated or formatted strings. """ content: str diff --git a/src/codegen/sdk/core/expressions/subscript_expression.py b/src/codegen/sdk/core/expressions/subscript_expression.py index 5de07b529..e69ecc575 100644 --- a/src/codegen/sdk/core/expressions/subscript_expression.py +++ b/src/codegen/sdk/core/expressions/subscript_expression.py @@ -26,6 +26,11 @@ class SubscriptExpression(Expression[Parent], Resolvable[Parent], Generic[Object Examples: A[] + + Attributes: + object: The object being indexed. + indices: A list of indices used for indexing the object. + """ object: Object diff --git a/src/codegen/sdk/core/expressions/ternary_expression.py b/src/codegen/sdk/core/expressions/ternary_expression.py index 8be571d4c..c3681cd3c 100644 --- a/src/codegen/sdk/core/expressions/ternary_expression.py +++ b/src/codegen/sdk/core/expressions/ternary_expression.py @@ -19,7 +19,13 @@ @apidoc class TernaryExpression(Expression[Parent], Chainable, Generic[Parent]): - """Any ternary expression in the code where a condition will determine branched execution.""" + """Any ternary expression in the code where a condition will determine branched execution. + + Attributes: + condition: The condition expression that determines which branch to execute. + consequence: The expression to execute if the condition is true. + alternative: The expression to execute if the condition is false. + """ condition: Expression[Self] | None consequence: Expression[Self] | None diff --git a/src/codegen/sdk/core/external_module.py b/src/codegen/sdk/core/external_module.py index efa41d751..7a57eba56 100644 --- a/src/codegen/sdk/core/external_module.py +++ b/src/codegen/sdk/core/external_module.py @@ -29,9 +29,11 @@ class ExternalModule( ): """Represents an external module, like `datetime`, that can be referenced. - These are only added to the graph during import resolution and will not exist in a local file's - subgraph. This is because we don't know what an import is referencing or resolves to until we - see the full codebase. + These are only added to the graph during import resolution and will not exist in a local file's subgraph. This is because we don't know what an import is referencing or resolves to until we see + the full codebase. + + Attributes: + node_type: The type of node, set to NodeType.EXTERNAL. """ node_type: Literal[NodeType.EXTERNAL] = NodeType.EXTERNAL diff --git a/src/codegen/sdk/core/file.py b/src/codegen/sdk/core/file.py index 00815adbb..140b9436b 100644 --- a/src/codegen/sdk/core/file.py +++ b/src/codegen/sdk/core/file.py @@ -54,6 +54,12 @@ class File(Editable[None]): """Represents a generic file. Could represent a source file or a non-code file such as a markdown file or image file. + + Attributes: + name: The name of the file. + file_path: The relative file path as a string. + path: The absolute path of the file as a Path object. + node_type: The type of node, set to NodeType.FILE. """ name: str @@ -432,6 +438,9 @@ class SourceFile( Enables creating, reading, updating, and deleting files and searching through their contents, etc. + + Attributes: + code_block: Represents the block of code contained in the file. """ code_block: TCodeBlock diff --git a/src/codegen/sdk/core/function.py b/src/codegen/sdk/core/function.py index d40cd1fa4..ee5a0bf31 100644 --- a/src/codegen/sdk/core/function.py +++ b/src/codegen/sdk/core/function.py @@ -50,7 +50,7 @@ class Function( """Abstract representation of a Function. Attributes: - return_type: the return type annotation of the function + symbol_type: The type of symbol, set to SymbolType.Function. """ symbol_type = SymbolType.Function diff --git a/src/codegen/sdk/core/import_resolution.py b/src/codegen/sdk/core/import_resolution.py index 9cf0bb74f..a1fb4ad71 100644 --- a/src/codegen/sdk/core/import_resolution.py +++ b/src/codegen/sdk/core/import_resolution.py @@ -61,17 +61,14 @@ class ImportResolution(Generic[TSourceFile]): class Import(Usable[ImportStatement], Chainable, Generic[TSourceFile], HasAttribute[TSourceFile]): """Represents a single symbol being imported. - For example, this is one `Import` in Python (and similar applies to Typescript, etc.): - ``` - from a.b import c - ``` - - This is two separate `Import` in Python: - ``` - from a.b import c, d # one import for each `c` and `d` - ``` Attributes: + to_file_id: The node ID of the file to which this import belongs. + module: The module from which the symbol is being imported, if applicable. symbol_name: The name of the symbol being imported. For instance import a as b has a symbol_name of a. + alias: The alias of the imported symbol, if one exists. + node_type: The type of node, set to NodeType.IMPORT. + import_type: The type of import, indicating how the symbol is imported. + import_statement: The statement that this import is part of. import_statement: the ImportStatement that this import belongs to """ diff --git a/src/codegen/sdk/core/interfaces/callable.py b/src/codegen/sdk/core/interfaces/callable.py index 6479dd4cb..83a2db7b9 100644 --- a/src/codegen/sdk/core/interfaces/callable.py +++ b/src/codegen/sdk/core/interfaces/callable.py @@ -43,6 +43,9 @@ class Callable(Usable, Generic[TParameter, TType]): """Any symbol that can be invoked with arguments eg. Function, Class, Decorator, ExternalModule + + Attributes: + return_type: The type of value returned by the callable, or a placeholder. """ _parameters: SymbolGroup[TParameter, Self] | list[TParameter] diff --git a/src/codegen/sdk/core/interfaces/editable.py b/src/codegen/sdk/core/interfaces/editable.py index 87378165c..30d8c0085 100644 --- a/src/codegen/sdk/core/interfaces/editable.py +++ b/src/codegen/sdk/core/interfaces/editable.py @@ -99,8 +99,12 @@ def _is_empty_container(text: str) -> bool: class Editable(JSONable, Generic[Parent]): """An editable instance is an abstract text representation of any text in a file. - The editable APIs enables text search and edit within the given Editable wrapper around any - group of text in a file. + Attributes: + ts_node: The TreeSitter node associated with this Editable instance. + file_node_id: The unique identifier for the file node. + G: The codebase graph that this Editable instance is part of. + parent: The parent node of this Editable instance. + node_type: The type of node this Editable instance represents. """ ts_node: TSNode diff --git a/src/codegen/sdk/core/interfaces/has_block.py b/src/codegen/sdk/core/interfaces/has_block.py index 6f791c716..678fee099 100644 --- a/src/codegen/sdk/core/interfaces/has_block.py +++ b/src/codegen/sdk/core/interfaces/has_block.py @@ -23,7 +23,11 @@ @apidoc class HasBlock(Expression, Generic[TCodeBlock, TDecorator]): - """An interface for any code object that has a block of code, e.g. a function, class, etc.""" + """An interface for any code object that has a block of code, e.g. a function, class, etc. + + Attributes: + code_block: The block of code associated with the code object. + """ code_block: TCodeBlock diff --git a/src/codegen/sdk/core/interfaces/supports_generic.py b/src/codegen/sdk/core/interfaces/supports_generic.py index e5d8d3c84..725df9076 100644 --- a/src/codegen/sdk/core/interfaces/supports_generic.py +++ b/src/codegen/sdk/core/interfaces/supports_generic.py @@ -15,6 +15,12 @@ class SupportsGenerics(Symbol, Generic[TType]): + """A symbol that supports generics. + + Attributes: + type_parameters: The type parameters of the symbol, if any. + """ + type_parameters: TypeParameters[TType, Self] | None = None @cached_property diff --git a/src/codegen/sdk/core/statements/assignment_statement.py b/src/codegen/sdk/core/statements/assignment_statement.py index f35d76f9b..3beac4781 100644 --- a/src/codegen/sdk/core/statements/assignment_statement.py +++ b/src/codegen/sdk/core/statements/assignment_statement.py @@ -35,6 +35,11 @@ class AssignmentStatement(Statement[TCodeBlock], HasValue, Generic[TCodeBlock, T This includes potentially multiple Assignments via `statement.assignments`, which represent each assignment of a value to a variable within this statement. For example, assigning to a destructured object, or assigning multiple values to multiple variables in a single statement. + + Attributes: + assignments: A list of assignments within the statement. + left: The left-hand side expression of the first assignment. + right: The right-hand side expression of the first assignment, or None if not applicable. """ statement_type = StatementType.ASSIGNMENT diff --git a/src/codegen/sdk/core/statements/attribute.py b/src/codegen/sdk/core/statements/attribute.py index ab1692acc..9316fc672 100644 --- a/src/codegen/sdk/core/statements/attribute.py +++ b/src/codegen/sdk/core/statements/attribute.py @@ -30,7 +30,11 @@ @apidoc class Attribute(AssignmentStatement[TCodeBlock, TAssignment], Usable, Chainable, Generic[TCodeBlock, TAssignment]): - """Abstract representation of an attribute on a class definition.""" + """Abstract representation of an attribute on a class definition. + + Attributes: + assignment: The assignment associated with the attribute. + """ statement_type = StatementType.CLASS_ATTRIBUTE assignment: TAssignment diff --git a/src/codegen/sdk/core/statements/block_statement.py b/src/codegen/sdk/core/statements/block_statement.py index 0597c9262..07eb02855 100644 --- a/src/codegen/sdk/core/statements/block_statement.py +++ b/src/codegen/sdk/core/statements/block_statement.py @@ -25,7 +25,11 @@ @apidoc class BlockStatement(Statement[TCodeBlock], HasBlock, ABC, Generic[TCodeBlock]): - """Statement which contains a block.""" + """Statement which contains a block. + + Attributes: + code_block: The code block contained within the statement, if it exists. + """ code_block: TCodeBlock | None diff --git a/src/codegen/sdk/core/statements/for_loop_statement.py b/src/codegen/sdk/core/statements/for_loop_statement.py index 3d3e635b1..e6c6bc4b4 100644 --- a/src/codegen/sdk/core/statements/for_loop_statement.py +++ b/src/codegen/sdk/core/statements/for_loop_statement.py @@ -26,7 +26,8 @@ class ForLoopStatement(BlockStatement[Parent], HasBlock, ABC, Generic[Parent]): """Abstract representation of the for loop. Attributes: - code_block: The code block that is executed in each iteration of the loop + item: The item being iterated over, if applicable. + iterable: The iterable expression that the loop iterates over. """ statement_type = StatementType.FOR_LOOP_STATEMENT diff --git a/src/codegen/sdk/core/statements/if_block_statement.py b/src/codegen/sdk/core/statements/if_block_statement.py index db8b347f6..31e2fcbe8 100644 --- a/src/codegen/sdk/core/statements/if_block_statement.py +++ b/src/codegen/sdk/core/statements/if_block_statement.py @@ -28,6 +28,7 @@ @apidoc class IfBlockStatement(Statement[TCodeBlock], Generic[TCodeBlock, TIfBlockStatement]): """Abstract representation of the if/elif/else if/else statement block. + For example, if there is a code block like: if condition1: block1 diff --git a/src/codegen/sdk/core/statements/raise_statement.py b/src/codegen/sdk/core/statements/raise_statement.py index 71e582294..c0c5146e4 100644 --- a/src/codegen/sdk/core/statements/raise_statement.py +++ b/src/codegen/sdk/core/statements/raise_statement.py @@ -25,10 +25,9 @@ class RaiseStatement(Statement[Parent], HasValue, Generic[Parent]): """Abstract representation of raise statements, e.g. in Python: - ```python - def f(x): - raise ValueError() - ``` + Example: + def f(x): + raise ValueError() """ statement_type = StatementType.RAISE_STATEMENT diff --git a/src/codegen/sdk/core/statements/return_statement.py b/src/codegen/sdk/core/statements/return_statement.py index 3b716362c..368c5e720 100644 --- a/src/codegen/sdk/core/statements/return_statement.py +++ b/src/codegen/sdk/core/statements/return_statement.py @@ -27,13 +27,12 @@ class ReturnStatement(Statement, HasValue, Generic[Parent, TCodeBlock]): """Abstract representation of return statements, e.g. in Python: - ```python - def f(x): - if x: + Example: + def f(x): + if x: return x**2 # ReturnStatement else: return 1 # ReturnStatement - ``` """ statement_type = StatementType.RETURN_STATEMENT diff --git a/src/codegen/sdk/core/statements/statement.py b/src/codegen/sdk/core/statements/statement.py index 7d4175c6e..88c5c807b 100644 --- a/src/codegen/sdk/core/statements/statement.py +++ b/src/codegen/sdk/core/statements/statement.py @@ -25,7 +25,29 @@ @apidoc class StatementType(StrEnum): - """Enum representing the different types of statements that can be parsed.""" + """Enum representing the different types of statements that can be parsed. + + Attributes: + COMMENT: Represents a comment statement. + ASSIGNMENT: Represents an assignment expression. + EXPRESSION_STATEMENT: Represents an expression statement. + CLASS_ATTRIBUTE: Represents a class attribute. + RETURN_STATEMENT: Represents a return statement. + RAISE_STATEMENT: Represents a raise statement. + WITH_STATEMENT: Represents a with statement. + PASS_STATEMENT: Represents a pass statement. + BREAK_STATEMENT: Represents a break statement. + LABELED_STATEMENT: Represents a labeled statement. + TRY_CATCH_STATEMENT: Represents a try-catch statement. + IF_BLOCK_STATEMENT: Represents an if block statement. + FOR_LOOP_STATEMENT: Represents a for loop statement. + WHILE_STATEMENT: Represents a while statement. + SWITCH_STATEMENT: Represents a switch statement. + SYMBOL_STATEMENT: Represents a symbol statement. + UNSPECIFIED: Represents any unparsed code snippet or graph node statements. + EXPORT_STATEMENT: Represents an export statement. + IMPORT_STATEMENT: Represents an import statement. + """ COMMENT = "comment" ASSIGNMENT = "assignment_expression" diff --git a/src/codegen/sdk/core/statements/switch_statement.py b/src/codegen/sdk/core/statements/switch_statement.py index 02276a081..c8af3431a 100644 --- a/src/codegen/sdk/core/statements/switch_statement.py +++ b/src/codegen/sdk/core/statements/switch_statement.py @@ -26,7 +26,8 @@ class SwitchStatement(Statement[Parent], Generic[Parent, TCodeBlock, TSwitchCase """Abstract representation of the switch statement. Attributes: - value: The value to switch on + value: The value to switch on. + cases: A list of switch cases. """ statement_type = StatementType.SWITCH_STATEMENT diff --git a/src/codegen/sdk/core/statements/symbol_statement.py b/src/codegen/sdk/core/statements/symbol_statement.py index 095a75288..22981a2ef 100644 --- a/src/codegen/sdk/core/statements/symbol_statement.py +++ b/src/codegen/sdk/core/statements/symbol_statement.py @@ -29,6 +29,9 @@ class SymbolStatement(Statement[Parent], Generic[Parent, Child]): Examples include: - a function definition, class definition, global variable assignment + + Attributes: + symbol: The symbol associated with this statement, representing a code element. """ statement_type = StatementType.SYMBOL_STATEMENT diff --git a/src/codegen/sdk/core/statements/while_statement.py b/src/codegen/sdk/core/statements/while_statement.py index 338f860da..033d7c7f2 100644 --- a/src/codegen/sdk/core/statements/while_statement.py +++ b/src/codegen/sdk/core/statements/while_statement.py @@ -26,7 +26,12 @@ @apidoc class WhileStatement(Statement[TCodeBlock], HasBlock, ABC, Generic[TCodeBlock]): - """Abstract representation of the while statement block.""" + """Abstract representation of the while statement block. + + Attributes: + condition: The condition expression of the while statement. + code_block: The code block that represents the body of the while statement. + """ statement_type = StatementType.WHILE_STATEMENT condition: Expression[Self] diff --git a/src/codegen/sdk/core/symbol.py b/src/codegen/sdk/core/symbol.py index b939a7cc4..a2deebb75 100644 --- a/src/codegen/sdk/core/symbol.py +++ b/src/codegen/sdk/core/symbol.py @@ -40,9 +40,11 @@ @apidoc class Symbol(Usable[Statement["CodeBlock[Parent, ...]"]], Generic[Parent, TCodeBlock]): - """Abstract representation of a Symbol in a Codebase. A Symbol is a top-level entity in a file, - e.g. a Function, Class, GlobalVariable, etc. + """Abstract representation of a Symbol in a Codebase. A Symbol is a top-level entity in a file, e.g. a Function, Class, GlobalVariable, etc. + Attributes: + symbol_type: The type of the symbol. + node_type: The type of the node, set to NodeType.SYMBOL. """ symbol_type: SymbolType diff --git a/src/codegen/sdk/core/symbol_groups/dict.py b/src/codegen/sdk/core/symbol_groups/dict.py index 7af4cb0d9..6e729e2fe 100644 --- a/src/codegen/sdk/core/symbol_groups/dict.py +++ b/src/codegen/sdk/core/symbol_groups/dict.py @@ -27,7 +27,11 @@ @apidoc class Pair(Editable[Parent], HasValue, Generic[TExpression, Parent]): - """An abstract representation of a key, value pair belonging to a `Dict`""" + """An abstract representation of a key, value pair belonging to a `Dict`. + + Attributes: + key: The key expression of the pair, expected to be of type TExpression. + """ key: TExpression @@ -77,7 +81,8 @@ def _compute_dependencies(self, usage_type: UsageKind | None = None, dest: HasNa class Dict(Expression[Parent], Builtin, MutableMapping[str, TExpression], Generic[TExpression, Parent]): """Represents a dict (object) literal the source code. - You can use standard Python operations to operate on this dict (i.e. `len`, `del`, `set`, `get`, etc) + Attributes: + unpack: An optional unpacking element, if present. """ _underlying: Collection[Pair[TExpression, Self] | Unpack[Self], Parent] diff --git a/src/codegen/sdk/core/type_alias.py b/src/codegen/sdk/core/type_alias.py index 7a74ab9db..5d162cb04 100644 --- a/src/codegen/sdk/core/type_alias.py +++ b/src/codegen/sdk/core/type_alias.py @@ -32,6 +32,10 @@ class TypeAlias(SupportsGenerics, HasValue, HasBlock, HasAttribute[TAttribute], """Abstract representation of a Type object. Only applicable for some programming languages like TypeScript. + + Attributes: + symbol_type: The type of symbol, set to SymbolType.Interface. + code_block: The code block associated with this type alias. """ symbol_type = SymbolType.Interface diff --git a/src/codegen/sdk/python/class_definition.py b/src/codegen/sdk/python/class_definition.py index f9648f8ab..6a5c28a68 100644 --- a/src/codegen/sdk/python/class_definition.py +++ b/src/codegen/sdk/python/class_definition.py @@ -25,7 +25,11 @@ @py_apidoc class PyClass(Class[PyFunction, PyDecorator, PyCodeBlock, PyParameter, PyType], PyHasBlock, PySymbol): - """Extends Class for Python codebases""" + """Extends Class for Python codebases + + Attributes: + constructor_keyword: The keyword used to identify the constructor method in Python classes. + """ _decorated_node: TSNode | None constructor_keyword = "__init__" diff --git a/src/codegen/sdk/python/file.py b/src/codegen/sdk/python/file.py index 3bd4f8391..1cd3ee0b3 100644 --- a/src/codegen/sdk/python/file.py +++ b/src/codegen/sdk/python/file.py @@ -26,7 +26,11 @@ @py_apidoc class PyFile(SourceFile[PyImport, PyFunction, PyClass, PyAssignment, Interface[PyCodeBlock, PyAttribute, PyFunction, PyType], PyCodeBlock], PyHasBlock): - """SourceFile representation for Python codebase""" + """SourceFile representation for Python codebase + + Attributes: + programming_language: The programming language of the file. Set to ProgrammingLanguage.PYTHON. + """ programming_language = ProgrammingLanguage.PYTHON diff --git a/src/codegen/sdk/python/statements/assignment_statement.py b/src/codegen/sdk/python/statements/assignment_statement.py index 9d18ab657..65d72f30c 100644 --- a/src/codegen/sdk/python/statements/assignment_statement.py +++ b/src/codegen/sdk/python/statements/assignment_statement.py @@ -26,8 +26,6 @@ class PyAssignmentStatement(AssignmentStatement["PyCodeBlock", PyAssignment]): """A class that represents a Python assignment statement in a codebase, such as `x = 1` or `a, b = 1, 2`. This includes potentially multiple Assignments via `statement.assignments`, which represent each assignment of a value to a variable within this statement. - - For example, assigning to a list, or assigning multiple values to multiple variables in a single statement. """ assignment_types = {"assignment", "augmented_assignment", "named_expression"} diff --git a/src/codegen/sdk/python/statements/comment.py b/src/codegen/sdk/python/statements/comment.py index 390107212..3675a713a 100644 --- a/src/codegen/sdk/python/statements/comment.py +++ b/src/codegen/sdk/python/statements/comment.py @@ -9,7 +9,14 @@ @py_apidoc class PyCommentType(StrEnum): - """Enum representing different types of comments.""" + """Enum representing different types of comments. + + Attributes: + SINGLE_LINE: Represents a single line comment. + MULTI_LINE_QUOTE: Represents a multi-line comment using single quotes. + MULTI_LINE_DOUBLE_QUOTE: Represents a multi-line comment using double quotes. + UNKNOWN: Represents an unknown type of comment. + """ SINGLE_LINE = "SINGLE_LINE" MULTI_LINE_QUOTE = "MULTI_LINE_QUOTE" diff --git a/src/codegen/sdk/python/statements/if_block_statement.py b/src/codegen/sdk/python/statements/if_block_statement.py index c0f8a4c09..872b3110f 100644 --- a/src/codegen/sdk/python/statements/if_block_statement.py +++ b/src/codegen/sdk/python/statements/if_block_statement.py @@ -21,6 +21,7 @@ @apidoc class PyIfBlockStatement(IfBlockStatement[Parent, "PyIfBlockStatement"], Generic[Parent]): """Pythons implementation of the if/elif/else statement block. + For example, if there is a code block like: if condition1: block1 diff --git a/src/codegen/sdk/python/statements/with_statement.py b/src/codegen/sdk/python/statements/with_statement.py index 3f8954c00..d507abdbd 100644 --- a/src/codegen/sdk/python/statements/with_statement.py +++ b/src/codegen/sdk/python/statements/with_statement.py @@ -39,8 +39,8 @@ class WithStatement(Statement["PyCodeBlock"], PyHasBlock): # code block Attributes: - code_block: (PyCodeBlock) the code block of the with statement - clause: the expression of the with clause + code_block: The code block of the with statement. + clause: The expression of the with clause. """ statement_type = StatementType.WITH_STATEMENT diff --git a/src/codegen/sdk/typescript/assignment.py b/src/codegen/sdk/typescript/assignment.py index b9a3ec6a1..0c9116d15 100644 --- a/src/codegen/sdk/typescript/assignment.py +++ b/src/codegen/sdk/typescript/assignment.py @@ -24,9 +24,6 @@ class TSAssignment(Assignment["TSAssignmentStatement | ExportStatement"], TSSymb Handles various types of TypeScript assignments including variable declarators, assignment expressions, augmented assignments, property signatures, and public field definitions. It provides functionality for manipulating assignments and managing their associated types and comments. - - Attributes: - assignment_types (list[str]): List of valid TypeScript assignment node types that this class can handle. """ assignment_types: list[str] = ["variable_declarator", "assignment_expression", "augmented_assignment_expression", "property_signature", "public_field_definition"] diff --git a/src/codegen/sdk/typescript/enum_definition.py b/src/codegen/sdk/typescript/enum_definition.py index 51c853170..2da12ef4a 100644 --- a/src/codegen/sdk/typescript/enum_definition.py +++ b/src/codegen/sdk/typescript/enum_definition.py @@ -28,7 +28,13 @@ @ts_apidoc class TSEnum(TSHasBlock, TSSymbol, HasAttribute[TSAttribute]): - """Representation of an Enum in TypeScript""" + """Representation of an Enum in TypeScript. + + Attributes: + symbol_type: The type of symbol, set to SymbolType.Enum. + body: The expression representing the body of the enum. + code_block: The code block associated with the enum. + """ symbol_type = SymbolType.Enum body: Expression[Self] diff --git a/src/codegen/sdk/typescript/export.py b/src/codegen/sdk/typescript/export.py index 24967852b..3ce36c824 100644 --- a/src/codegen/sdk/typescript/export.py +++ b/src/codegen/sdk/typescript/export.py @@ -44,7 +44,13 @@ @ts_apidoc class TSExport(Export["Collection[TSExport, ExportStatement[TSExport]]"], HasValue, Chainable): - """Represents a single exported symbol. There is a 1:M relationship between an ExportStatement and an Export""" + """Represents a single exported symbol. + + There is a 1:M relationship between an ExportStatement and an Export + + Attributes: + node_type: The type of the node, set to NodeType.EXPORT. + """ _declared_symbol: TSSymbol | TSImport | None _exported_symbol: Name | None diff --git a/src/codegen/sdk/typescript/expressions/conditional_type.py b/src/codegen/sdk/typescript/expressions/conditional_type.py index b17789526..fce03749f 100644 --- a/src/codegen/sdk/typescript/expressions/conditional_type.py +++ b/src/codegen/sdk/typescript/expressions/conditional_type.py @@ -25,6 +25,12 @@ class TSConditionalType(Type[Parent], Generic[Parent]): Examples: typeof s + + Attributes: + left: The left-hand side type of the conditional type. + right: The right-hand side type of the conditional type. + consequence: The type if the condition is true. + alternative: The type if the condition is false. """ left: "TSType[Self]" diff --git a/src/codegen/sdk/typescript/expressions/function_type.py b/src/codegen/sdk/typescript/expressions/function_type.py index 6b00e0510..14126c02d 100644 --- a/src/codegen/sdk/typescript/expressions/function_type.py +++ b/src/codegen/sdk/typescript/expressions/function_type.py @@ -26,16 +26,17 @@ class TSFunctionType(Type[Parent], Generic[Parent]): """Function type definition. + Example: + a: (a: number) => number + Attributes: return_type: Return type of the function. - - Examples: - a: (a: number) => number + name: This lets parameters generate their node_id properly. """ return_type: "TSType[Self] | TSReturnTypePlaceholder[Self]" _parameters: Collection[TSParameter, Self] - name: None = None # This lets parameters generate their node_id properly + name: None = None def __init__(self, ts_node: TSNode, file_node_id: NodeId, G: "CodebaseGraph", parent: Parent): super().__init__(ts_node, file_node_id, G, parent) diff --git a/src/codegen/sdk/typescript/expressions/lookup_type.py b/src/codegen/sdk/typescript/expressions/lookup_type.py index 7ee97f6d6..207747296 100644 --- a/src/codegen/sdk/typescript/expressions/lookup_type.py +++ b/src/codegen/sdk/typescript/expressions/lookup_type.py @@ -23,8 +23,13 @@ @ts_apidoc class TSLookupType(Type[Parent], Generic[Parent]): """Type lookup + Examples: a["key"] + + Attributes: + type: The type of the TypeScript object being looked up. + lookup: The expression used for the lookup operation. """ type: "TSType[Self]" diff --git a/src/codegen/sdk/typescript/expressions/query_type.py b/src/codegen/sdk/typescript/expressions/query_type.py index 4c34f849e..80a678cc1 100644 --- a/src/codegen/sdk/typescript/expressions/query_type.py +++ b/src/codegen/sdk/typescript/expressions/query_type.py @@ -24,7 +24,10 @@ class TSQueryType(Type[Parent], Generic[Parent]): """Type query Examples: - typeof s + typeof s + + Attributes: + query: The TypeScript type associated with the query. """ query: "TSType[Self]" diff --git a/src/codegen/sdk/typescript/expressions/readonly_type.py b/src/codegen/sdk/typescript/expressions/readonly_type.py index 10079de66..865b1528f 100644 --- a/src/codegen/sdk/typescript/expressions/readonly_type.py +++ b/src/codegen/sdk/typescript/expressions/readonly_type.py @@ -25,6 +25,9 @@ class TSReadonlyType(Type[Parent], Generic[Parent]): Examples: readonly s + + Attributes: + type: The underlying TypeScript type associated with this readonly type. """ type: "TSType[Self]" diff --git a/src/codegen/sdk/typescript/file.py b/src/codegen/sdk/typescript/file.py index 6ba3d2d7a..852947fcc 100644 --- a/src/codegen/sdk/typescript/file.py +++ b/src/codegen/sdk/typescript/file.py @@ -33,7 +33,12 @@ @ts_apidoc class TSFile(SourceFile[TSImport, TSFunction, TSClass, TSAssignment, TSInterface, TSCodeBlock], TSHasBlock, Exportable): - """Extends the SourceFile class to provide TypeScript-specific functionality.""" + """Extends the SourceFile class to provide TypeScript-specific functionality. + + Attributes: + programming_language: The programming language of the file. Set to ProgrammingLanguage.TYPESCRIPT. + ts_config: The ts_config file nearest to this file. + """ programming_language = ProgrammingLanguage.TYPESCRIPT ts_config: TSConfig | None = None diff --git a/src/codegen/sdk/typescript/namespace.py b/src/codegen/sdk/typescript/namespace.py index f4131d67b..9d29c16ea 100644 --- a/src/codegen/sdk/typescript/namespace.py +++ b/src/codegen/sdk/typescript/namespace.py @@ -29,7 +29,12 @@ @ts_apidoc class TSNamespace(TSSymbol, TSHasBlock, HasName): - """Representation of a namespace module in TypeScript""" + """Representation of a namespace module in TypeScript. + + Attributes: + symbol_type: The type of the symbol, set to SymbolType.Namespace. + code_block: The code block associated with this namespace. + """ symbol_type = SymbolType.Namespace code_block: TSCodeBlock diff --git a/src/codegen/sdk/typescript/statements/assignment_statement.py b/src/codegen/sdk/typescript/statements/assignment_statement.py index 2b49b923c..974279168 100644 --- a/src/codegen/sdk/typescript/statements/assignment_statement.py +++ b/src/codegen/sdk/typescript/statements/assignment_statement.py @@ -24,12 +24,7 @@ @ts_apidoc class TSAssignmentStatement(AssignmentStatement["TSCodeBlock", TSAssignment]): - """A class that represents a TypeScript assignment statement in a codebase, such as `const x = 1` or `const { a: b } = myFunc()`. - - This includes potentially multiple Assignments via `statement.assignments`, which represent each assignment of a value to a variable within this statement. - - For example, assigning to a destructured object, or assigning multiple values to multiple variables in a single statement. - """ + """A class that represents a TypeScript assignment statement in a codebase, such as `const x = 1` or `const { a: b } = myFunc()`.""" assignment_types = {"assignment_expression", "augmented_assignment_expression", "variable_declarator", "public_field_definition", "property_signature"} diff --git a/src/codegen/sdk/typescript/statements/labeled_statement.py b/src/codegen/sdk/typescript/statements/labeled_statement.py index d8f2c38e4..3a9b5eb7e 100644 --- a/src/codegen/sdk/typescript/statements/labeled_statement.py +++ b/src/codegen/sdk/typescript/statements/labeled_statement.py @@ -36,6 +36,9 @@ class TSLabeledStatement(Statement[Parent], HasName, Generic[Parent]): ``` emptyStatement: { pass } ``` + + Attributes: + body: The body of the labeled statement, which can be an Expression or None. """ statement_type = StatementType.LABELED_STATEMENT diff --git a/src/codegen/sdk/typescript/ts_config.py b/src/codegen/sdk/typescript/ts_config.py index 806621c5c..bb213c255 100644 --- a/src/codegen/sdk/typescript/ts_config.py +++ b/src/codegen/sdk/typescript/ts_config.py @@ -19,7 +19,13 @@ @ts_apidoc class TSConfig: - """TypeScript configuration file specified in tsconfig.json, used for import resolution and computing dependencies.""" + """TypeScript configuration file specified in tsconfig.json, used for import resolution and computing dependencies. + + Attributes: + config_file: The configuration file object representing the tsconfig.json file. + config_parser: The parser used to interpret the TypeScript configuration. + config: A dictionary containing the parsed configuration settings. + """ config_file: File config_parser: "TSConfigParser" diff --git a/src/codegen/sdk/typescript/type_alias.py b/src/codegen/sdk/typescript/type_alias.py index 52961296c..d4d671909 100644 --- a/src/codegen/sdk/typescript/type_alias.py +++ b/src/codegen/sdk/typescript/type_alias.py @@ -12,7 +12,11 @@ @ts_apidoc class TSTypeAlias(TypeAlias[TSCodeBlock, TSAttribute], TSSymbol, TSHasBlock): - """Representation of an Interface in TypeScript""" + """Representation of an Interface in TypeScript. + + Attributes: + symbol_type: The type of symbol, set to SymbolType.Type. + """ symbol_type = SymbolType.Type diff --git a/tests/unit/codegen/sdk/code_generation/test_api_doc_generation.py b/tests/unit/codegen/sdk/code_generation/test_api_doc_generation.py index d6e72cf85..c60d59eba 100644 --- a/tests/unit/codegen/sdk/code_generation/test_api_doc_generation.py +++ b/tests/unit/codegen/sdk/code_generation/test_api_doc_generation.py @@ -40,17 +40,17 @@ def test_api_doc_generation_sanity(codebase, language: ProgrammingLanguage) -> N other_lang = "TS" if language == ProgrammingLanguage.PYTHON else "Py" # =====[ Python ]===== docs = get_codegen_sdk_docs(language=language, codebase=codebase) - assert count_tokens(docs) < 55000 + assert count_tokens(docs) < 70000 assert f"{lang}Function" in docs assert f"{lang}Class" in docs assert f"{other_lang}Function" not in docs # assert "InviteFactoryCreateParams" in docs # Canonicals aren't in docs -@pytest.mark.timeout(160) +@pytest.mark.timeout(300) @pytest.mark.xdist_group("codegen") def test_mdx_api_doc_generation_sanity(codebase) -> None: - docs_json = generate_docs_json(codebase, "HEAD") + docs_json = generate_docs_json(codebase, "HEAD", raise_on_missing_docstring=True) assert len(docs_json.classes) > 0