Docs suggestion for use with existing simple projects

[philgyford]

I've been trying to get up and running with uv on an existing Django project and I feel the (otherwise very good) docs have a familiar problem from other package managers: for someone who's creating Python-based websites, or other projects that aren't going to be packaged and redistributed, some of the tool and its docs, confuse matters.

For example, Creating a new project creates a file structure with a src/ directory, which I rarely/never see in repos that are things like Django sites, Flask sites, etc.

Then the next section Working on an existing project makes it sound simpler than it is. If I do commands like uv run ... then I end up with errors[1] about the structure of my project. While the error provides three options for solving it, none of them mean much to me, even after googling, as someone who's worked on Python websites for years but done very little packaging of projects.

Another common need is to install dev requirements locally, but non-dev requirements in production. While there's a dev-dependencies in the settings I can't see anywhere that explains how to install them in my local virtualenv.

I am old and tired and may have missed things, but I think there could be some clarity for those who know nothing about src directories, or eggs, wheels, and building packages, and who just want to work on a simple non-packaged project.

[1]

error: Multiple top-level packages discovered in a flat-layout: ['conf', 'hines', 'docker', 'assets', 'node_modules'].

To avoid accidental inclusion of unwanted files or directories,
setuptools will not proceed with this build.

If you are trying to create a single distribution with multiple packages
on purpose, you should not rely on automatic discovery.
Instead, consider the following options:

1. set up custom discovery (`find` directive with `include` or `exclude`)
2. use a `src-layout`
3. explicitly set `py_modules` or `packages` with a list of names

To find more information, look for "package discovery" on setuptools docs.

[charliermarsh]

This is good feedback -- thank you. I think the docs are slightly more oriented towards new projects right now.

We also don't have great support for what I would call "virtual" projects: Python projects that don't have a package structure.

[zanieb]

This is tough because the complaint isn't from our tool, it's from setuptools which we use as a default build backend for legacy compatibility. Unfortunately, this is causing other problems, e.g. #6456.

It's becoming obvious that we need a better solution for projects that don't define a build backend, instead of throwing a legacy tool at your project and letting it complain about the structure. Opening #6462 to discuss that more general problem.

[weihenglim]

Yes would definitely love to see more support for projects that don't require a build system. I am currently pushing to replace pipenv with uv for dependency management in several Django projects but the pain points that are holding us back are:

• The inability to install both development and production dependencies in a virtual project. We could initialize the projects without the --virtual flag but that requires some manual wrangling of the pyproject.toml file to make things work.
• Having to jump through several hoops to install the set of locked dependencies to the system environment. uv sync --frozen forces the creation of a virtual environment while there doesn't seem to be a way to uv pip install from the uv.lock file.

Basically we just want to use uv to manage dependencies without having to bother with project structure, build backends, packaging tools, etc. At the moment pipenv does a great job at this but it is sorely lacking in speed especially for our larger projects (version resolution and locking could take tens of minutes)

[philgyford]

Yep, all of that. Hopefully uv can improve that side of things a bit more, because it seems so good otherwise.

If it can, I feel the docs could also be tweaked a bit to make it easier for people who only create what @charliermarsh calls "virtual" projects, including beginners. All the stuff in the docs about building reusable packages for distribution makes uv more confusing than necessary for them/me. It's hard to know what to ignore, and what's essential vs optional.

It seems like the docs for this and similar tools are (understandably) written by people for whom building and distributing Python packages is common and obvious. But for people like me (I've done it a couple of times, never want to again) who only make Python websites etc, it makes the tools seem unnecessarily complicated.

I don't know if there's a way to separate parts of the docs out more, so that someone making "virtual" projects can ignore stuff about building etc until they need it, but that would be great. The danger, I guess, is then making the docs longer or less useful for the package-building developers. But thinking through what a Python newbie, making a Flask website for example, needs, and moving unnecessary details out of the way, might help?

[zanieb]

We will address this in https://github.com/astral-sh/uv/issues/6511

[zanieb]

As of uv v0.4.0, we now support "simple" projects by default! This includes a bunch of documentation changes targeting "application" developers and I even tried the Flask tutorial. I hope this is helpful. If you have any problems please let us know.