Add Python package

[ofek]

Hello again! This is the second half of what we require in order to start using DotSlash.

This moves over the code for the dotslash Python package I created over the weekend. The ownership transfer on PyPI is in progress.

The package serves a similar purpose to the existing fb-dotslash Node.js package stored in the top level node directory. Some notes:

• Python 3.9 is EOL at the end of the month so I chose to require 3.10+.
• The package exposes a single locate function for finding the path to the binary that was installed by the installation. The logic was adapted from equivalents like UV's finder. I optimized the path resolution to perform as little work as necessary and to do so lazily.

  ❯ docker run --rm -it python:3.14 bash
  root@8a442038a1c8:/# curl -fsSL https://github.com/sharkdp/hyperfine/releases/download/v1.19.0/hyperfine-v1.19.0-x86_64-unknown-linux-musl.tar.gz \
  | tar -xzO 'hyperfine-v1.19.0-x86_64-unknown-linux-musl/hyperfine' \
  | install -m 0755 /dev/stdin /usr/local/bin/hyperfine
  root@8a442038a1c8:/# pip install -qqq dotslash uv
  root@8a442038a1c8:/# hyperfine -m 100 --warmup 10 "python -m timeit -n 1 -r 1 -s 'from uv import find_uv_bin' 'find_uv_bin()'"
  Benchmark 1: python -m timeit -n 1 -r 1 -s 'from uv import find_uv_bin' 'find_uv_bin()'
    Time (mean ± σ):      33.6 ms ±   2.4 ms    [User: 25.3 ms, System: 7.6 ms]
    Range (min … max):    30.3 ms …  46.1 ms    100 runs
  
  root@8a442038a1c8:/# hyperfine -m 100 --warmup 10 "python -m timeit -n 1 -r 1 -s 'from dotslash import locate' 'locate()'"
  Benchmark 1: python -m timeit -n 1 -r 1 -s 'from dotslash import locate' 'locate()'
    Time (mean ± σ):      23.5 ms ±   1.0 ms    [User: 17.8 ms, System: 5.7 ms]
    Range (min … max):    22.1 ms …  26.9 ms    127 runs
  
  root@8a442038a1c8:/# # Show time it takes to locate binaries
  root@8a442038a1c8:/# python -m timeit -n 1 -r 1 -s "from uv import find_uv_bin" "find_uv_bin()"
  1 loop, best of 1: 7.71 msec per loop
  root@8a442038a1c8:/# # This includes the time of all imports (still faster)
  root@8a442038a1c8:/# python -m timeit -n 1 -r 1 -s "from dotslash import locate" "locate()"
  1 loop, best of 1: 2.86 msec per loop
  root@8a442038a1c8:/# # This excludes import times to match eager behavior of UV
  root@8a442038a1c8:/# python -m timeit -n 1 -r 1 -s "from dotslash import locate,_locate" "locate()"
  1 loop, best of 1: 1.14 msec per loop
  

• The shipped binary can be invoked directly with python -m dotslash. If there ever is a desire to represent paths as anything other than strings in the implementation, please don't.
• Builds require setting the DOTSLASH_VERSION environment variable to the desired release tag of DotSlash (the v is optional). This will be used as the package version and, by default, for fetching the appropriate release artifact.
• Rather than making HTTP requests during builds, you can set the DOTSLASH_SOURCE environment variable to the path to a directory containing the release artifacts. I strongly recommend that the release process uses that eventually (and the Node.js package's build script gains support).
• I remove build instructions from the content of the PyPI project's landing page since the information wouldn't be useful for users.
• I moved the release jobs of the downstream packages into a separate workflow that only executes when called by the primary release workflow. I already configured Trusted Publishing on PyPI to use the release-downstream.yml workflow from this repository. You might find hazy details about their support for reusable workflows but this comment provides the full picture. Basically, the claim they chose happens to work for the most nested called workflow when using reusable workflows but not the top level one. Whenever support for that happens there will be no user impact for existing supported scenarios.

---

cc @sdwilsh @bigfootjon for review as requested

Also, it's worth noting that PyPI was blocking the name dotslash due to certain rules and @di very graciously provided the override 🙇‍♂️

[meta-codesync]

@facebook-github-bot has imported this pull request. If you are a Meta employee, you can view this in D84891338. (Because this pull request was imported automatically, there will not be any future comments.)

[sdwilsh]

This moves over the code for the dotslash Python package I created over the weekend. The ownership transfer on PyPI is in progress.

I have accepted this invitation, but I won't complete the ownership transfer until this gets merged in.

I am pretty happy with how this looks at a quick glance, but I will do a more thorough review next week. I will probably open a PR on your fork to address some of the devcontainer stuff I see that should be addressed with this as well.

[ofek]

Thanks, sounds good! I pushed some final cleanup changes like making sure the licenses are shipped with each wheel.

[sdwilsh]

back to you for mostly minor stuff. This is great, and thanks for putting it together!

[sdwilsh]

Annoyingly, we don't seem to have a global ruff.toml file that I can just have included by default. Internal linters are not upset with the formatting here, so it's fine, but something for me to look into in the future I guess -_-

[bigfootjon]

We should enable ufmt: https://ufmt.omnilib.dev/en/stable/

(unfortunately, private wiki links follow)

@sdwilsh see: https://www.internalfb.com/wiki/Python/code_formatting/ruff/

We should follow this wiki: https://www.internalfb.com/wiki/Python/code_formatting/pyfmt/#replicating-pyfmt-in-ope

Which will require updating the imported Diff a bit. @sdwilsh do you have capacity to go do that?

[ofek]

Is Ruff unsupported internally i.e. you must use ufmt?

[sdwilsh]

Ah, this makes sense. All the ruff things I saw were for other open source projects.

[sdwilsh]

I will see if I can get this working today. I'm unfortunately off tomorrow, so if it doesn't happen today, I'll get it resolved on Monday.

[sdwilsh]

It looks like ufmt can use ruff, if I'm reading the internal wiki properly, so I will see about making this work today.

[bigfootjon]

Looks reasonable, but I think we need to reflect pyfmt correctly. I don't really have capacity right now but Shawn might

(sorry for how long it took to review this PR)

[bigfootjon]

We should enable ufmt: https://ufmt.omnilib.dev/en/stable/

(unfortunately, private wiki links follow)

@sdwilsh see: https://www.internalfb.com/wiki/Python/code_formatting/ruff/

We should follow this wiki: https://www.internalfb.com/wiki/Python/code_formatting/pyfmt/#replicating-pyfmt-in-ope

Which will require updating the imported Diff a bit. @sdwilsh do you have capacity to go do that?

[ofek]

Okay, I think I addressed everything now! The only exception is the Ruff/ufmt feedback but as you know I don't have access to the documentation on what needs doing.

[bigfootjon]

@sdwilsh can you re-review? And message me internally about what to do about the formatter stuff?

[ofek]

The error is happening on main as well; the last successful run was on September 18. It started failing on September 30 with a commit that seemingly only modified dependencies of the website.

[sdwilsh]

@ofek, I have another PR open on your repository to get ufmt working. There's a flag there about me not updating the readme that you'll probably want to look at.
ofek#2

[ofek]

I merged it in, thanks! Shout out to @amyreese for ufmt troubleshooting help in Discord regarding both an issue in the VS Code extension and a workaround for an issue in a dependency 🙏

[sdwilsh]

My TODO list is longer than I have time left today, but I should be able to get this wrapped up tomorrow. I'll have to make one additional internal change to land this to get the formatting internally to not fight with the external formatter.

[sdwilsh]

I'm somewhat partial to doing this in the devcontainer workflow, but I'm not going to block merging this on that.

[sdwilsh]

This isn't right anymore, is it? I guess technically we kinda do use ruff via ufmt, so maybe it sorta is? I won't block on this; we can fix it post merge.

[ofek]

I don't think the badge requires the direct use of the CLI, as long as the tool is used.

[sdwilsh]

Despite my best efforts, the internal linter still changed two pieces of python code. I'm going to land it internally anyway, and I'll debug what setting we need to fix externally once this is merged.

[meta-codesync]

@sdwilsh merged this pull request in 228a528.

[sdwilsh]

I guess the good news is that the GitHub lint is also happy with the changes the internal linter made. Hurray? That will probably be a problem for future me at some point, but it's good enough for now :D

Thanks for this contribution, @ofek! And thanks to both @di and @amyreese for helping along the way!

[ofek]

Thanks a lot everyone!