Skip to content

Commit e118718

Browse files
committed
Update FAQ to better explain running FD outside of project env
The investigations in issue #460 reveal that for now we are likely less backwards-compatible than we'd like to be. Until that situation is improved, let's tell users to open an issue if they encounter problems. This should help us gauge how to prioritize this.
1 parent b7568ed commit e118718

File tree

1 file changed

+44
-15
lines changed

1 file changed

+44
-15
lines changed

README.md

+44-15
Original file line numberDiff line numberDiff line change
@@ -574,14 +574,18 @@ run for each `libX`:
574574
fawltydeps libX
575575
```
576576

577-
### Why must FawltyDeps run in the same Python environment as my project dependencies?
577+
### Does FawltyDeps need to run in the same Python environment as my project?
578578

579-
(This is no longer true since FawltyDeps v0.11: FawltyDeps should be able to
580-
automatically find your project dependencies when they are installed in a Python
581-
environment that exists within your project. If your project dependencies are
582-
installed elsewhere, you can point FawltyDeps in their direction with `--pyenv`,
583-
as explained above in the section on
584-
[Python environment mapping](#python-environment-mapping))
579+
No (not since FawltyDeps v0.11). FawltyDeps should be able to automatically find
580+
your project dependencies when they are installed in a Python environment that
581+
exists within your project. If your project dependencies are installed
582+
elsewhere, you can point FawltyDeps in their direction with `--pyenv`, as
583+
explained above in the section on
584+
[Python environment mapping](#python-environment-mapping)).
585+
586+
See also the next question for more details.
587+
588+
### Why does FawltyDeps need a Python environment with my project dependencies?
585589

586590
The reason why FawltyDeps need to find your project dependencies _somewhere_ is
587591
that the core logic of FawltyDeps needs to match `import` statements in your
@@ -610,14 +614,39 @@ they provide. This is:
610614
i.e. the one in which FawltyDeps itself is running.
611615

612616
As a final resort, when an installed package is not found for a declared
613-
dependency, the
614-
_identity mapping_ that FawltyDeps falls back to will still do a good job for
615-
the majority of dependencies where the import name is indeed identical to the
616-
package name that you depend on.
617-
618-
This is an area of active development in FawltyDeps, and we are
619-
[working on better solutions](https://github.com/tweag/FawltyDeps/issues/195),
620-
to avoid having to fall back to this identity mapping.
617+
dependency, the _identity mapping_ that FawltyDeps falls back to will still do
618+
a good job for the majority of dependencies where the import name is indeed
619+
identical to the package name that you depend on.
620+
621+
### My project is using Python version before v3.7, can I still use FawltyDeps?
622+
623+
Yes! Even though FawltyDeps itself runs on Python >=v3.7, we try to support
624+
analyzing projects that run on any version of Python 3.
625+
626+
As explained in the previous two questions, FawltyDeps itself does not need to
627+
run inside the same Python environment as your project and its dependencies.
628+
629+
You can instead install FawltyDeps using a newer Python version (e.g. via
630+
[uvx](https://docs.astral.sh/uv/guides/tools/#running-tools) or
631+
[pipx](https://github.com/pypa/pipx)). Then run FawltyDeps from inside your
632+
project directory. If your project has an embedded Python environment (e.g.
633+
under `.venv/`) then FawltyDeps should automatically find it and use it to
634+
analyze your project dependencies. Alternatively, you can always use `--pyenv`
635+
to point FawltyDeps to where your dependencies are installed.
636+
637+
Currently the lowest Python version that your project can use (and still be
638+
analyzed by FawltyDeps) is determined by our use of the
639+
[`ast` module](https://docs.python.org/3/library/ast.html#module-ast) in the
640+
Python standard library: As long as your project's Python syntax is compatible
641+
with the Python version that FawltyDeps runs on, you should be fine. If you run
642+
into problems with older Python syntax (e.g. using `async` or `await` as
643+
variable names), please open an issue, and we'll look into extending our
644+
support further.
645+
646+
A final resort can be to downgrade to an older version of FawltyDeps that is
647+
compatible with the Python version used in your project. Currently, the only
648+
Python version we have dropped support for is v3.7, and FawltyDeps v0.18 is
649+
the last release to support this Python version.
621650

622651
### Why does FawltyDeps fail to match `sklearn` with `scikit-learn`?
623652

0 commit comments

Comments
 (0)