| name | flight-profiler-module |
| description | Translate a file path to its Python module name in a running Python process. Use this when you know a file path but need the module name for commands like watch, trace, or reload. |
flight-profiler-module
Translate a file path to its corresponding Python module name. Most diagnostic commands (watch, trace, reload, getglobal) require a module name — use this to find it from a file path.
Prerequisites: Read the flight-profiler-attach skill first for platform requirements, installation, permissions, and connection details.
When to Use
- You know the file path but not the module name needed by watch/trace/reload/getglobal
- The module name isn't obvious from the file structure (e.g., namespace packages, src layouts)
- You want to confirm the exact module name as seen by the target process's
sys.modules
Usage
flight_profiler <pid> --cmd "module <filepath>" --no-color
Arguments
filepath — Absolute or relative path to the Python source file. The path is resolved to an absolute path and checked for existence on the client side before sending to the target process.
Output Format
Success — returns the module name as plain text:
__main__
Failure (file not imported) — the file exists but is not loaded in the target process:
filepath: /path/to/file.py is not imported in target process.
Failure (file not found) — the path does not exist on disk (checked client-side):
✗ Parse module argument failed: filepath /path/to/file.py does not exist.
Examples
1. Main script file
The entry-point script is always __main__:
flight_profiler <pid> --cmd "module /Users/zy/workspace/app/main_script.py" --no-color
__main__
2. Standard library module
flight_profiler <pid> --cmd "module /Users/zy/miniforge3/envs/py39/lib/python3.9/json/__init__.py" --no-color
json
3. Module name may differ from file name
os.path on POSIX is actually backed by posixpath.py. The module command returns the real module name:
flight_profiler <pid> --cmd "module /Users/zy/miniforge3/envs/py39/lib/python3.9/posixpath.py" --no-color
posixpath
This is why querying the target process is important — the module name depends on sys.modules, not the file path structure.
4. File exists but not imported by target process
flight_profiler <pid> --cmd "module /Users/zy/workspace/app/unused_module.py" --no-color
filepath: /Users/zy/workspace/app/unused_module.py is not imported in target process.
This means the file was never imported — the module name cannot be resolved. Check if the code path that uses this file has been triggered.
5. File path does not exist
flight_profiler <pid> --cmd "module /nonexistent/path.py" --no-color
✗ Parse module argument failed: filepath /nonexistent/path.py does not exist.
Typical Workflow
The module command is a prerequisite step for other diagnostic commands. Use it when you only have a file path:
flight_profiler <pid> --cmd "module /home/admin/myapp/services/order.py" --no-color
flight_profiler <pid> --cmd "watch myapp.services.order OrderService process_order -n 1" --no-color
flight_profiler <pid> --cmd "trace myapp.services.order OrderService process_order -n 1" --no-color
flight_profiler <pid> --cmd "getglobal myapp.services.order config" --no-color
Tips
- The module name depends on the target process's
sys.path, which may differ from what you'd expect
- This command queries the target process for the actual module mapping via
sys.modules, so it always gives the correct name
- If the file is not imported yet (lazy import, conditional import), trigger the code path first, then retry
- For the main entry-point script, the module name is always
__main__
Related Commands
- watch / trace / reload / getglobal — all require module name as first argument
Source Files
- CLI plugin:
flight_profiler/plugins/module/cli_plugin_module.py
- Parser:
flight_profiler/plugins/module/module_parser.py
- Server plugin:
flight_profiler/plugins/module/server_plugin_module.py
