_internal/README.md

[tony]

These are MIT licensed python parts. You're welcome to copy them and augment them in your project as you see fit.

However, they're not supported. Maintainers can break these APIs between patch releases without warning (no deprecation policy).

If you find something in here useful, feel free to file an issue that'd you find it helpful to stabilize the API or see it in a project of its own. Also as it's MIT licensed, you can make your own package based on it at any time.

[tony]

parse: detect and parse VCS Urls

• Modify individual parts
• Extensible

cmd:

• Tightly integrated to vcs system

  Git.clone()
  Svn.checkout()
  Mercurial.clone()

• Typed

• Executor:

  • subprocess (Default)
  • SubprocessCommand (return Dataclass object for fine-grained control)

sync: High-level VCS syncing

• Uniform base API across VCS Systems

  Implement the same functions:

  .obtain()
  .update()

[tony]

Design spec

• Dictionary-based:
  Everything should be operable via a JSON dictionary (yes, encoding class is allowed)

  Every of consequence should really be an object literal / hashmap / whatever.

• Doctest everything

• Pytest w/ parametrize everything

• Test infrastructure and tooling - make it so convenient that exceptions can create a pytest of the crash

• Everything that matters be introspectable, and lazy to maximize test capability

  • Everything should be namedtuple, typeddict, or dataclass

    Dataclass is nice simply because dot notation is easier to type, complete, and read

  • Easy immutability / freezing to make it easier for jobs / async / parallelism

    • If immutable, make it easy to clone a copy with alterations

  • Easy to mutate? Allow easy way to mutate in single case scenarios?

• Document everything

  • Go back every quarter and reread the docs, actively think about the optics, highlighting the value, examples, documentations to make sure everything is there and minimize frustration. Think in the shoes of a new user unfamiliar with the API and seeing if the package fits or not

• Annotate and mypy everything

• Keep APIs unstable until you get right

• CI for lint and run tests

[tony]

Are you at a Mercurial shop? Can you help make us jimmy this module into the next Sunbeam toaster of python modules? We need this patch and shimmy this module into shape but seek a skilled tradesperson to give it - in Robert M. Pirsig's sense - care. Connect with us on the tracker.

Subversion is rare to come by, but there's mechanics who get by just servicing Audis. Do you have the Mike Rowe tradeskill to tape this module up, even if the OEM parts aren't around anymore? Apply in the issues thread. The API will stay frozen until we're satisfied this puppy is safe to drive.

[tony]

• allow weighting / ordering matchers. lower weight, higher precedence
• is_explicit / is_narrow (e.g. vcs match)
• is_distinct (only matches against one matcher, only used on is_valid())