diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8762e5cbb..8fee75bd0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,11 +26,52 @@ git commit -m "Description of your changes" git push origin your-branch-name ``` -9. **Submit a Pull Request (PR)**: Open a PR from your forked repository to the main branch of this repo. -> Important: Describe the changes you've made clearly! +8. **Submit a Pull Request (PR)**: Open a PR from your forked repository to the main branch of this repo. + > Important: Describe the changes you've made clearly! Our maintainers will review your PR, and once everything is good, your contributions will be merged! +## Code Style and Documentation + +### Python Code Style + +We use Ruff for code linting and formatting. Please ensure your code passes all linting checks before submitting a PR. + +### Docstring Conventions + +We follow Google-style docstrings with these specific conventions: + +- Class docstrings should fully document all parameters used in `__init__` +- We don't require separate docstrings for `__init__` methods when parameters are documented in the class docstring +- Property methods should have docstrings explaining their purpose and return value + +Example of correctly documented class: + +```python +class MyClass: + """Class description. + + Additional details about the class. + + Args: + param1: Description of first parameter. + param2: Description of second parameter. + """ + + def __init__(self, param1, param2): + # No docstring required here as parameters are documented above + self.param1 = param1 + self.param2 = param2 + + @property + def some_property(self) -> str: + """Get the formatted property value. + + Returns: + A string representation of the property. + """ + return f"Property: {self.param1}" +``` # Contributor Covenant Code of Conduct @@ -51,23 +92,23 @@ diverse, inclusive, and healthy community. Examples of behavior that contributes to a positive environment for our community include: -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience -* Focusing on what is best not just for us as individuals, but for the overall +- Focusing on what is best not just for us as individuals, but for the overall community Examples of unacceptable behavior include: -* The use of sexualized language or imagery, and sexual attention or advances of +- The use of sexualized language or imagery, and sexual attention or advances of any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email address, +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a +- Other conduct which could reasonably be considered inappropriate in a professional setting ## Enforcement Responsibilities @@ -162,4 +203,4 @@ For answers to common questions about this code of conduct, see the FAQ at [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html [Mozilla CoC]: https://github.com/mozilla/diversity [FAQ]: https://www.contributor-covenant.org/faq -[translations]: https://www.contributor-covenant.org/translations \ No newline at end of file +[translations]: https://www.contributor-covenant.org/translations diff --git a/docs/api/index.rst b/docs/api/index.rst index ce7c22113..199aed1dd 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -45,8 +45,10 @@ Transport & Serialization Utilities ~~~~~~~~~ +* :mod:`Adapters ` * :mod:`Clocks ` * :mod:`Metrics ` +* :mod:`Observers ` * :mod:`Sync ` * :mod:`Transcriptions ` * :mod:`Utils ` @@ -56,10 +58,12 @@ Utilities :caption: API Reference :hidden: + Adapters Audio Clocks Frames Metrics + Observers Pipeline Processors Serializers diff --git a/pyproject.toml b/pyproject.toml index 87c5c1835..f4727286d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -115,6 +115,9 @@ select = [ "D", # Docstring rules "I", # Import rules ] +# We ignore D107 because class docstrings already document __init__ parameters +# and our Sphinx configuration uses napoleon_include_init_with_doc=True +ignore = ["D107"] [tool.ruff.lint.pydocstyle] convention = "google" diff --git a/src/pipecat/adapters/schemas/function_schema.py b/src/pipecat/adapters/schemas/function_schema.py index f6e59cef1..55a070cf9 100644 --- a/src/pipecat/adapters/schemas/function_schema.py +++ b/src/pipecat/adapters/schemas/function_schema.py @@ -8,16 +8,22 @@ from typing import Any, Dict, List class FunctionSchema: + """Standardized function schema representation for tool definition. + + Provides a structured way to define function tools used with AI models like OpenAI. + This schema defines the function's name, description, parameter properties, and + required parameters, following specifications required by AI service providers. + + Args: + name: Name of the function to be called. + description: Description of what the function does. + properties: Dictionary defining parameter types, descriptions, and constraints. + required: List of property names that are required parameters. + """ + def __init__( self, name: str, description: str, properties: Dict[str, Any], required: List[str] ) -> None: - """Standardized function schema representation. - - :param name: Name of the function. - :param description: Description of the function. - :param properties: Dictionary defining properties types and descriptions. - :param required: List of required parameters. - """ self._name = name self._description = description self._properties = properties @@ -26,7 +32,8 @@ class FunctionSchema: def to_default_dict(self) -> Dict[str, Any]: """Converts the function schema to a dictionary. - :return: Dictionary representation of the function schema. + Returns: + Dictionary representation of the function schema. """ return { "name": self._name, @@ -40,16 +47,36 @@ class FunctionSchema: @property def name(self) -> str: + """Get the function name. + + Returns: + The function name. + """ return self._name @property def description(self) -> str: + """Get the function description. + + Returns: + The function description. + """ return self._description @property def properties(self) -> Dict[str, Any]: + """Get the function properties. + + Returns: + Dictionary of parameter specifications. + """ return self._properties @property def required(self) -> List[str]: + """Get the required parameters. + + Returns: + List of required parameter names. + """ return self._required