Skip to content

Fix docs that name the wrong alias attribute and wrong classes - #14

Closed
iskandr wants to merge 1 commit into
masterfrom
deslop/docstrings
Closed

iskandr wants to merge 1 commit into
masterfrom
deslop/docstrings

Conversation

@iskandr

@iskandr iskandr commented Sep 14, 2026

Copy link
Copy Markdown
Collaborator

This PR only changes docs and docstrings.

  • Alias attribute name. README.md told users to define _KEYWORD_ALIASES, and so did the comment in Serializable._update_kwargs. The code reads only _SERIALIZABLE_KEYWORD_ALIASES (serializable.py:83, dataclass_serializable.py:74), so following the README silently did nothing. Both now use the correct name.
  • Wrong class names. The Serializable docstrings called it the "base class for all PyEnsembl objects" and described to_json, write_json_file, and read_json_file as working on a Genome or VariantCollection. They now describe generic objects.
  • Class docstring. It said a user-defined to_dict is required, but Serializable.to_dict has a default. It now says only that the to_dict() keys must match the __init__ arguments.
  • Python 2 comment. Removed the comment in __reduce__ explaining a Python 2 pickling limitation.
  • Typos. Fixed "serializble" in the README and "wasn't isn't" in helpers.to_dict.
  • Version. Bumped the patch version to 1.1.1, per AGENTS.md.

Checks: ./lint.sh and ./test.sh pass (42 tests).

https://claude.ai/code/session_01DctgBZ5rJiuNzpWXqrNguT

- README and a comment in Serializable._update_kwargs referred to
  _KEYWORD_ALIASES; the attribute the code reads is
  _SERIALIZABLE_KEYWORD_ALIASES.
- Serializable docstrings described PyEnsembl objects, a Genome, and a
  VariantCollection, and said a user-defined to_dict is required even
  though a default is provided.
- Drop the Python 2 pickling comment in __reduce__.
- Fix typos in README and helpers.to_dict.
- Bump version to 1.1.1.

Claude-Session: https://claude.ai/code/session_01DctgBZ5rJiuNzpWXqrNguT
@coveralls

Copy link
Copy Markdown

Coverage Report for CI Build 34868032726

Coverage remained the same at 89.778%

Details

  • Coverage remained the same as the base build.
  • Patch coverage: No coverable lines changed in this PR.
  • 7 coverage regressions across 1 file.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

7 previously-covered lines in 1 file lost coverage.

File Lines Losing Coverage Coverage
serializable.py 7 82.98%

Coverage Stats

Coverage Status
Relevant Lines: 225
Covered Lines: 202
Line Coverage: 89.78%
Coverage Strength: 0.9 hits per line

💛 - Coveralls

iskandr added a commit that referenced this pull request Oct 6, 2026
Serializable provides a default to_dict, so it doesn't need a user-defined
one; also fix the grammar in to_serializable_repr's helper docstring.

Claude-Session: https://claude.ai/code/session_01JyZ1WTFWJ3EZ41QdYzKwGP
iskandr added a commit that referenced this pull request Oct 6, 2026
Serializable's inherited docstrings named VariantCollection, Genome and
PyEnsembl, which leaked into downstream API docs (e.g. PyEnsembl's
Genome.read_json_file). Make them generic, and fix a code comment that
still named the old `_KEYWORD_ALIASES` hook.

Adds a write_json_file/read_json_file round-trip test (previously
uncovered).

Fixes #17

* Fix two more inaccurate docstrings from #14

Serializable provides a default to_dict, so it doesn't need a user-defined
one; also fix the grammar in to_serializable_repr's helper docstring.

Claude-Session: https://claude.ai/code/session_01JRDMg3F5kNKmnjv5jvQBgr
Claude-Session: https://claude.ai/code/session_01JyZ1WTFWJ3EZ41QdYzKwGP
@iskandr

iskandr commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

Superseded: every change here is now on master. The alias rename and README fixes came in with #19, and the class-name docstring fixes, the default to_dict wording and the to_serializable_repr grammar fix with #18 (bde506a). Both are released in 1.1.2.

@iskandr iskandr closed this Oct 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants