refactor: name each module for its mechanism, not for the scheme - #132
Merged
Conversation
A module name must tell a developer what to implement. It must not name the
policy, the scheme, the department or the state. That context belongs in the
docstring beside the host and the vintage.
21 modules move. Each new name states the transport and the artefact:
sansad -> parliament_qa_api
questions_list -> question_list_api
committees -> committee_report_api
debates -> verbatim_pdf_api
attendance -> attendance_json_api
bills -> bill_catalog_api
prs -> drupal_publication_index
cag -> audit_pdf_index
ddg -> ministry_pdf_index
doe -> pay_report_index
niti -> annual_report_index
census -> ogd_resource_api
dchb_town -> ogd_town_release
mospi -> rest_dataset_api
indiacode -> statute_dspace
abhilekh_patal -> catalogue_search_api
myneta -> affidavit_pages
courts -> case_law_api
neva -> assembly_portal
neva_portals -> assembly_portal_registry
neva_text -> two_column_pdf_qa
Nothing breaks. Every old path stays as a shim that binds the SAME module
object, so `from commoner_probe.sansad import SansadProbe` and
`monkeypatch.setattr("commoner_probe.sansad.f", ...)` both still reach the code
that runs. Re-exporting a copy would hand a patcher one object and the running
code another. tests/test_module_aliases.py asserts the identity, the warning,
and the exact module paths five sibling repos import today. Verified from a
built wheel in a clean venv, not only from the source tree.
The CLI is untouched. Subcommand names are the operator's interface and name
the source the operator wants; renaming them buys a developer nothing.
Data identifiers are untouched, and that boundary is what makes this safe.
Manifest kinds, schema filenames, record fields, corpus filenames and the
`extractor` provenance string are written into corpora already on disk. The
first pass rewrote two of them; the tests caught it, and both are restored with
a comment saying why they keep their original spelling.
… it is
The module name states the mechanism. The docstring must state the rest, or
the context is lost rather than moved.
Every renamed module now opens with one line of mechanism and a CONTEXT block.
The block names the operator, the host, the scheme and the access constraint.
ogd_resource_api ORGI produces the data. NIC operates the API. The API
needs a key, and the published sample key returns one
demo row.
drupal_publication_index PRS is a private body. The pages carry an All
Rights Reserved footer and no usable terms.
case_law_api Indian Kanoon is a private service. The reference client
is MIT, so this repo reimplements its wire contract.
assembly_portal NeVA is a Ministry programme. Each State runs its own
deployment at <state>.neva.gov.in.
parliament_qa_api had no module docstring at all. It has one now.
The blocks follow ASD-STE100: one idea per sentence, active voice, simple
tenses, and the same word for the same thing.
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.
A module name must tell a developer what to implement. It must not name the
policy, the scheme, the department or the state. That context belongs in the
docstring, beside the host and the vintage.
The audit
47 modules were read. Three classes came out of it.
Already correct (21).
http_client,url_safety,browser,wayback,textparse,base,corpus,records,validate,runlog,resolver,entities,evidence,stats,topics,dspace,nada. The conventionexisted. It was applied inconsistently.
Renamed (21). Listed below.
Duplication the naming hid.
indiacodeanddspaceboth defineparse_browse_page, andindiacode's own docstring says it is a legacy DSpaceinstall.
doeandnitiare one mechanism, andniti's docstring says so.Consolidating them changes behaviour, so it is not in this PR. The names now
make the duplication visible.
The renames
sansadparliament_qa_apiquestions_listquestion_list_apicommitteescommittee_report_apidebatesverbatim_pdf_apiattendanceattendance_json_apibillsbill_catalog_apiprsdrupal_publication_indexcagaudit_pdf_indexddgministry_pdf_indexdoepay_report_indexnitiannual_report_indexcensusogd_resource_apidchb_townogd_town_releasemospirest_dataset_apiindiacodestatute_dspaceabhilekh_patalcatalogue_search_apimynetaaffidavit_pagescourtscase_law_apinevaassembly_portalneva_portalsassembly_portal_registryneva_texttwo_column_pdf_qaNothing breaks
Every old path stays as a shim. The shim binds the SAME module object, so both
of these still reach the code that runs:
Re-exporting a copy would hand a patcher one object and the running code
another.
tests/test_module_aliases.pyasserts the identity, the deprecationwarning, and the exact module paths five sibling repos import today.
Verified from a built wheel in a clean venv, not only from the source tree.
All eleven consumer import paths resolve, and the CLI runs.
The CLI is untouched. Subcommand names are the operator's interface and
name the source an operator asks for. Renaming them buys a developer nothing.
The boundary that makes this safe
Data identifiers do not move. Manifest kinds, schema filenames, record fields,
corpus filenames and the
extractorprovenance string are written into corporaalready on disk.
The first pass rewrote two of them: the corpus filename
questions_list.jsonland the
extractorvalue recorded in every question row. The tests caughtboth. Both are restored, with a comment saying why they keep their original
spelling.
Verification
1,305 passed, ruff clean.
test_pyproject_version_matches_package_versionfails here and on untouched
master, because the venv is an editable installof a different worktree.
Not in this PR
The two consolidations, and the two open PRs (#130, #131) which will need a
rebase onto these names.