Skip to content

refactor(py)!: encapsulate dotpromptz internal modules behind private prefixes - #626

Merged
huangjeff5 merged 10 commits into
feat/dotpromptz-python-handlebarsfrom
feat/dotpromptz-private-api
Oct 5, 2026
Merged

huangjeff5 merged 10 commits into
feat/dotpromptz-python-handlebarsfrom
feat/dotpromptz-private-api

Conversation

@huangjeff5

@huangjeff5 huangjeff5 commented Oct 2, 2026 •

Copy link
Copy Markdown
Collaborator

New code imports from dotpromptz. Published genkit still imports the old module paths. Those imports do not warn.

# new code
from dotpromptz import DataArgument, DirStore, Dotprompt, Message

# still works for pip install genkit (0.12.0), no warning
from dotpromptz.dotprompt import Dotprompt
from dotpromptz.typing import DataArgument, PromptFunction, PromptInputConfig, PromptMetadata

Decisions

  • Published genkit 0.12.0 still imports the old modules, silently: pip install genkit depends on dotpromptz>=0.1.5 with no ceiling and imports dotpromptz.dotprompt and dotpromptz.typing. Those modules, plus stores, errors, helpers, parse, picoschema, resolvers, and util, re-export the private modules and print nothing. We chose silence over a DeprecationWarning because that import lives inside published genkit, and the app cannot change it. Remove the modules once genkit no longer installs this package that way.
  • Dotprompt's public signatures import from the root: compile() returns PromptFunction, and the constructor takes HelperFn, EscapeFunction, JsonSchema, PromptInputConfig, ModelConfigT, and VariablesT. Those names are exported from dotpromptz.
  • Root dotpromptz is the door for new code: Implementation modules are _dotprompt, _typing, _stores, and the other _ modules. New callers import from dotpromptz, not from those files.

@github-actions github-actions Bot added documentation Improvements or additions to documentation python dotpromptz labels Oct 2, 2026
@huangjeff5
huangjeff5 force-pushed the feat/dotpromptz-private-api branch 2 times, most recently from 6b8d787 to affaad3 Compare October 2, 2026 06:40
@huangjeff5
huangjeff5 added this pull request to stack #625 October 2, 2026 06:44
@huangjeff5 huangjeff5 changed the title refactor(py): make dotpromptz internal modules private and standardize root API surface refactor(py)!: encapsulate dotpromptz internal modules behind private prefixes Oct 2, 2026
@huangjeff5
huangjeff5 force-pushed the feat/dotpromptz-private-api branch from affaad3 to 8a2303f Compare October 2, 2026 07:09
@huangjeff5
huangjeff5 requested a review from pavelgj October 2, 2026 08:16
@huangjeff5
huangjeff5 force-pushed the feat/dotpromptz-private-api branch from dde6105 to ce8961f Compare October 2, 2026 09:29

@pavelgj pavelgj left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few comments/questions

Comment thread python/dotpromptz/src/dotpromptz/__init__.py
Comment thread python/dotpromptz/src/dotpromptz/__init__.py Outdated
@huangjeff5
huangjeff5 force-pushed the feat/dotpromptz-private-api branch 4 times, most recently from eb2774c to d36cd9a Compare October 3, 2026 00:45
@huangjeff5
huangjeff5 requested a review from pavelgj October 3, 2026 02:12

@pavelgj pavelgj left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM with comments

Comment thread python/dotpromptz/src/dotpromptz/__init__.py
@huangjeff5

Copy link
Copy Markdown
Collaborator Author

@gemini review

…e root API surface

- Rename dotpromptz internal modules with leading underscores (_dotprompt.py, _errors.py,
  _helpers.py, _models.py, _parse.py, _picoschema.py, _picoschema_reverse.py, _resolvers.py,
  _typing.py, _util.py, _validate.py).
- Rename internal subpackages to _stores/ and _adapters/.
- Standardize dotpromptz/__init__.py to re-export only the intentional public API surface
  (Dotprompt, DataArgument, PromptData, PromptMetadata, RenderedPrompt, Message, Role,
  Part, TextPart, MediaPart, DataPart, DirStore, DirStoreSync, DirStoreOptions,
  DotpromptError, FrontmatterError, PartialCycleError, ResolverFailedError,
  picoschema_to_json_schema).
- Update tests and documentation to import public symbols from the root package.
@huangjeff5
huangjeff5 force-pushed the feat/dotpromptz-private-api branch from 024541e to c0a9ac2 Compare October 5, 2026 19:00
@huangjeff5
huangjeff5 merged commit 856196b into main Oct 5, 2026
136 of 137 checks passed
@huangjeff5
huangjeff5 deleted the feat/dotpromptz-private-api branch October 5, 2026 19:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation dotpromptz python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants