Several items from a new user (e.g., unclear how to try out flit locally; --env flag not respected?; a working "quick start" demo?)

[jzohrab]

Hello, this is my first time using flit and a .toml file, and I wasn't sure how to get started with local testing to ensure everything is good. This issue contains a few initial thoughts and reactions on using flit. Let me know how I can organize this or contribute back to the project for other newcomers. And possibly all of this will spawn a "RTFM" thread of replies, which is usually valid.

Need docs on how to test locally?

I had a draft toml file with my dependencies set, and I believe everything is ok. To verify my work, I wanted to do the following:

• call a local build without pushing to pypi, have the package be available
• in a new environment, totally separate folder, run my built package
• check

This is similar to how I test docker, .exes, etc: I do a build, and then in a totally separate spot I run the thing. I don't need to push to an external location, it's all kept internal until it's ready.

What I ended up doing, which doesn't quite seem to do what I wanted:

0. Create the basic toml file, which includes a [project.scripts] lute = "lute.main:start" section
1. Create new directory and venv python3 -m venv .venv; source .venv/bin/activate
2. Run a local install into the environment: flit -f ../lute_v3/pyproject.toml install --env

Since my toml had 'scripts', it created a small file in /opt/homebrew/bin/lute, and I could run my project.

Issue? Docs on how to load requirements

Perhaps this is a toml issue, and not a flit issue, but it seems to be a challenge on how to reconcile tracking reqs in requirements.txt vs in the toml file. I ended up using pipdeptree to find the top-level dependencies, but couldn't find any suggestions on the "best" way to handle this.

Issue? --env flag not respected?

When I say flit didn't do what I wanted: I had supplied the --env flag, and so I thought that flit would install things into the .venv, but instead it put them in /opt/homebrew/opt/python@3.11/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/.

Docs on "scripts" entry ?

On my mac, the "scripts" created a small file , /opt/homebrew/bin/lute ... it's not clear what it will do on other systems (win, 'nix).

Summary for quickstart

A working quickstart for users to run and adapt to their project could be useful. I usually prefer to work from a shell of running code, and adapt it to my work, rather than read a bunch of docs and try to write my own bad examples.

• Add a dead-simple working application with one or two dependencies
• in readme or example, show commands to install locally
• give example of using the package/running the app

update docs to follow pypi 2FA requirement

pypi now requires 2FA, so the .pypirc file now seemingly can only use token for the username.

Unclear how to use dynamic with version.

I needed the version to be in my published package, as well as in the toml file. I didn't want to record the version info in 2 places, too easy to screw up. The docs at https://flit.pypa.io/en/latest/pyproject_toml.html say:

Version number as a string. If you want Flit to get this from a __version__ attribute, leave it out of the TOML config and include “version” in the dynamic field.

but I initially had no idea where to put that attribute or how to read it. I found this SO answer and it worked fine: in <my_pkg_dir>/__init__.py, added __version__ = "0.0.1.post4", in the toml: dynamic = ['version'], and the publish worked fine.

—-

Cheers and thank you very much!le

[takluyver]

Thank you! It might be a little while before I can go through this in detail, but it's really useful to get a sense of what's confusing to new users, so thank you for taking the time to write it up. 😊

…

On Sat, 4 Nov 2023, 23:36 JZ, ***@***.***> wrote: Hello, this is my first time using flit and a .toml file, and I wasn't sure how to get started with local testing to ensure everything is good. This issue contains a few initial thoughts and reactions on using flit. Let me know how I can organize this or contribute back to the project for other newcomers. And possibly all of this will spawn a "RTFM" thread of replies, which is usually valid. Need docs on how to test locally? I had a draft toml file with my dependencies set, and I *believe* everything is ok. To verify my work, I wanted to do the following: - call a local build without pushing to pypi, have the package be available - in a new environment, totally separate folder, run my built package - check This is similar to how I test docker, .exes, etc: I do a build, and then in a totally separate spot I run the thing. I don't need to push to an external location, it's all kept internal until it's ready. What I ended up doing, which *doesn't quite* seem to do what I wanted: 1. Create the basic toml file, which includes a [project.scripts] lute = "lute.main:start" section 2. Create new directory and venv python3 -m venv .venv; source .venv/bin/activate 3. Run a local install into the environment: flit -f ../lute_v3/pyproject.toml install --env Since my toml had 'scripts', it created a small file in /opt/homebrew/bin/lute, and I could run my project. Issue? Docs on how to load requirements Perhaps this is a toml issue, and not a flit issue, but it seems to be a challenge on how to reconcile tracking reqs in requirements.txt vs in the toml file. I ended up using pipdeptree to find the top-level dependencies, but couldn't find any suggestions on the "best" way to handle this. Issue? --env flag not respected? When I say flit didn't do what I wanted: I had supplied the --env flag, and so I thought that flit would install things into the .venv, but instead it put them in ***@***.*** /Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/. Docs on "scripts" entry ? On my mac, the "scripts" created a small file , /opt/homebrew/bin/lute ... it's not clear what it will do on other systems (win, 'nix). Summary for quickstart A working quickstart for users to run and adapt to their project could be useful. I usually prefer to work from a shell of running code, and adapt it to my work, rather than read a bunch of docs and try to write my own bad examples. - Add a dead-simple working application with one or two dependencies - in readme or example, show commands to install locally - give example of using the package/running the app Cheers and thank you very much!le — Reply to this email directly, view it on GitHub <#664>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACQB5I7IKW6U3I56HLVO5TYC3GRLAVCNFSM6AAAAAA654VQZCVHI2DSMVQWIX3LMV43ASLTON2WKOZRHE3TONJVGQ3DQMA> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[jzohrab]

It might be a little while before I can go through this in detail

Np, I know this is a messy issue, I couldn’t see how to separate things out without creating a tangled web of issues. Normally with OSS I contribute code or docs back, but at this point it would be a bad idea. Maybe with a bit more time I’ll sort out where the right spots are and I can PR back.

I added a note about 2FA.

Cheers!

[jzohrab]

Actually, if this PR has draft PRs enabled, I could open a long running draft pr for you to check, if that helps. (Sometimes bad PRs create more work and headaches!)

[takluyver]

Well, I said it would take me a while to get to this... 😄

So, first off, let's try to answer the questions here.

• Local testing: what you're doing basically works, but --env means 'the environment that Flit is running in', not 'the virtualenv that's active in your shell'. The way to do say the latter is --python=python (i.e. install to the Python which I can currently launch as python).
  • The way I think about it, your Homebrew Python environment is also an environment, but not a virtual environment. But this is admittedly confusing, because we often only talk about environments when we're using venv or conda.
  • Alternatively, you can use pip install . - so long as pip is installed in your venv, this will install your package there.
• requirements.txt vs requirements in pyproject.toml - usually you'd just use one or the other. Projects which are being packaged to go on PyPI need requirements in pyproject.toml, and so usually won't have a requirements.txt (except for specific things like building docs). A requirements.txt file is more common for application code. There's more background in this old blog post (pyproject.toml is more or less a modern replacement for setup.py).
  • If you do need both, I think pip-tools can work from pyproject.toml and generate requirements.txt.
  • If you're used to other languages, you may be trying to emulate a 'lock file'. Flit doesn't do that - if you want that model, try Poetry or PDM. There have been some efforts to standardise a lock file format, but that hasn't happened yet.
• --env flag - see above
• 'Scripts' - sorry, I'm so used to this I forget it may not be obvious. The general idea is to make a command to use from the command line (a shell like bash or zsh for Unix, the 'Command prompt' on Windows). On Linux & Mac, that just requires a text file. On Windows, there will be a .exe wrapper. flit install actually calls pip to do the installation, and pip uses distlib to generate those exe wrappers.
• Quickstart - we've got what I think of as a quickstart on the front page of the docs, which should show everything you need to package something with Flit. There's really not a lot it needs But maybe we should point to some real-world examples to see how everything fits together. My astsearch project is a straightforward one, although I do need to update that to new-style metadata... 😳
• 2FA - yes, good point, it's all tokens now. You can still have your username in .pypirc, though - it will look up tokens in keyring using the 'usernames' pypi_token:project:<project_name> and pypi_token:user:<username> (filling in your project name & username). This does need to be documented, though.
• Using dynamic with version: yup, you've done what that sentence tries to describe, but it could be clearer, especially with an example.

Thanks! I'll try to find ways to make these things clearer.

[jzohrab]

Thanks for the update. After my initial issues getting things working, everything is fine now, to the point where I've forgotten my original questions. :-)

fyi - I'm using Flit in my project Lute, publishing to pypi lute3. Works great, no issues. Thank you!

[takluyver]

Glad to hear it! 😃