Add docstrings to public APIs in dictknife.loading and submodules - #213
Merged
Conversation
This commit adds comprehensive English docstrings to all public functions and classes within the `src/dictknife/loading/` directory and its submodules. Key changes include: - Docstrings for `Loader`, `Dumper`, `Dispatcher` classes and their methods in `__init__.py`. - Docstrings for shortcut functions (`load`, `loads`, `dump`, `dumps`, etc.) in `__init__.py`. - Docstrings for `load` and `dump` (where applicable) in format-specific modules (json, yaml, toml, csv, tsv, md, raw, env, spreadsheet). - Mention of required optional dependencies (e.g., `ruamel.yaml` for yaml, `tomlkit` for toml, `google-api-python-client` for spreadsheet) and how to install them (e.g., `pip install dictknife[load]`). - Clarification of behavior for specific arguments (e.g., `sort_keys` for TOML, `errors` for CSV). - Improved error handling and robustness in some loaders (e.g., `env.py`, `md.py`, `csv.py`). - Type hints were added or refined in several places for clarity.
…rings This commit refactors the docstrings related to optional dependencies. - Detailed information about optional dependencies and their installation (e.g., using `pip install dictknife[extra]`) is now primarily located in the `Loader` and `Dumper` class docstrings in `src/dictknife/loading/__init__.py`. - Docstrings in format-specific modules (yaml, toml, spreadsheet) and for shortcut functions (`loadfile`, `dumpfile` in `__init__.py`) have been simplified. They now only mention the direct package dependency (e.g., "requires `ruamel.yaml`") and refer to the `Loader`/`Dumper` class docstrings or project documentation for more detailed installation instructions. This approach reduces redundancy and centralizes the information about optional dependencies, making it easier for users to understand the requirements for different file formats.
This commit further refines the documentation of optional dependencies: - Information about optional dependencies (e.g., for YAML, TOML, Spreadsheets) and their installation (e.g., `pip install dictknife[extra]`) is primarily consolidated within the `Loader` and `Dumper` class docstrings in `src/dictknife/loading/__init__.py`. - Docstrings in format-specific submodules (`yaml.py`, `toml.py`, `spreadsheet.py`) now omit direct mentions of required packages (e.g., "requires `ruamel.yaml`"). Users should rely on import statements or the centralized `Loader`/`Dumper` documentation for such details. - Shortcut functions `loadfile` and `dumpfile` in `__init__.py` have their docstrings updated to clearly direct users to the `Loader`/`Dumper` class docstrings or the project's main documentation for information on optional dependencies. This approach centralizes dependency information, reduces redundancy, and clarifies that submodules focus on API usage rather than repeating installation details better covered by `pyproject.toml` and centralized documentation.
This commit includes two main changes:
1. Refactor docstrings for optional dependencies:
* Information about optional dependencies (e.g., for YAML, TOML,
Spreadsheets) and their installation (e.g., `pip install dictknife[extra]`)
is now primarily consolidated within the `Loader` and `Dumper` class
docstrings in `src/dictknife/loading/__init__.py`.
* Docstrings in format-specific submodules (`yaml.py`, `toml.py`,
`spreadsheet.py`) now omit direct mentions of required packages.
* Shortcut functions `loadfile` and `dumpfile` in `__init__.py` have their
docstrings updated to clearly direct users to the `Loader`/`Dumper` class
docstrings or the project's main documentation for information on optional
dependencies.
2. Fix Markdown dump behavior in `src/dictknife/loading/md.py`:
* Ensures that `None` values in the input data are rendered as the string
specified by the `null_value` parameter (defaults to "null").
* Ensures that empty string `""` values in the input data are rendered as
empty strings (empty cells) in the Markdown table.
* This change addresses a test failure where the Markdown output for `None`
and empty strings was inconsistent with previous behavior or expectations.
This commit includes two main sets of changes:
1. Refactor docstrings for optional dependencies:
* Information about optional dependencies (e.g., for YAML, TOML,
Spreadsheets) and their installation (e.g., `pip install dictknife[extra]`)
is now primarily consolidated within the `Loader` and `Dumper` class
docstrings in `src/dictknife/loading/__init__.py`.
* Docstrings in format-specific submodules (`yaml.py`, `toml.py`,
`spreadsheet.py`) now omit direct mentions of required packages.
Users should rely on import statements or the centralized `Loader`/`Dumper`
documentation for such details.
* Shortcut functions `loadfile` and `dumpfile` in `__init__.py` have their
docstrings updated to clearly direct users to the `Loader`/`Dumper` class
docstrings or the project's main documentation for information on optional
dependencies.
2. Fix Markdown dump behavior in `src/dictknife/loading/md.py`:
* Ensures that if a key is not present in a row, it's rendered as an
empty cell (`""`).
* If a key is present and its value is `None`, it's rendered as the string
specified by the `null_value` parameter (defaults to "null").
* If a key is present and its value is an empty string `""`, it's rendered
as an empty cell (`""`).
* Other values are rendered as their string representation.
* This addresses a test failure and aligns the output with the expected
behavior for different types of missing/empty data.
This commit includes three main sets of changes:
1. Refactor docstrings for optional dependencies:
* Information about optional dependencies (e.g., for YAML, TOML,
Spreadsheets) and their installation (e.g., `pip install dictknife[extra]`)
is now primarily consolidated within the `Loader` and `Dumper` class
docstrings in `src/dictknife/loading/__init__.py`.
* Docstrings in format-specific submodules (`yaml.py`, `toml.py`,
`spreadsheet.py`) now omit direct mentions of required packages.
* Shortcut functions `loadfile` and `dumpfile` in `__init__.py` have their
docstrings updated to clearly direct users to the `Loader`/`Dumper` class
docstrings or the project's main documentation for information on optional
dependencies.
2. Fix Markdown dump behavior in `src/dictknife/loading/md.py`:
* Ensures that if a key is not present in a row, it's rendered as an
empty cell (`""`).
* If a key is present and its value is `None`, it's rendered as the string
specified by the `null_value` parameter (defaults to "null").
* If a key is present and its value is an empty string `""`, it's rendered
as an empty cell (`""`).
* Other values are rendered as their string representation.
3. Apply code formatting using `black`.
* Relevant source files in `src/dictknife/loading/` were reformatted.
Owner
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This commit adds comprehensive English docstrings to all public functions and classes within the
src/dictknife/loading/directory and its submodules.Key changes include:
Loader,Dumper,Dispatcherclasses and their methods in__init__.py.load,loads,dump,dumps, etc.) in__init__.py.loadanddump(where applicable) in format-specific modules (json, yaml, toml, csv, tsv, md, raw, env, spreadsheet).ruamel.yamlfor yaml,tomlkitfor toml,google-api-python-clientfor spreadsheet) and how to install them (e.g.,pip install dictknife[load]).sort_keysfor TOML,errorsfor CSV).env.py,md.py,csv.py).