Python files can be recorded

[kgilpin]

appmap-python currently refuses to record Python code that isn't in a module. This is a barrier to getting the desired data in some cases, especially for simple projects.

If the path setting in appmap.yml matches the name of a Python file, that file should be instrumented.

[github-actions]

Title

Enable AppMap to record individual Python files specified in appmap.yml

Problem

The current implementation of appmap-python does not record Python code that isn't part of a module. This behavior limits the ability to record simple projects or individual files specified by their path in appmap.yml.

Analysis

AppMap is designed to record function executions, HTTP requests, and database transactions in supported languages through dynamic instrumentation. For appmap-python, the tool auto-detects and instruments Python modules defined in the appmap.yml configuration file. However, it currently ignores individual Python files not part of a module, which can be restrictive in some scenarios.

To resolve this, we need to modify the configuration and file loading mechanisms to detect and instrument individual Python files if their path is specified in appmap.yml. This involves:

1. Config Processing: Adjusting the processing of the appmap.yml configuration to recognize and validate individual file paths.
2. Instrumentation: Extending the instrumentation functions to handle individual Python files in addition to modules.
3. File Loading: Ensuring proper loading and handling of these individual Python files in the recorder.

Proposed Changes

1. _appmap/configuration.py

   • Update the find_top_packages method to include scanning for individual .py files.
   • Modify the _resolve_relative_to method to resolve paths for individual Python files.
   • Validate the configuration to accept file paths in addition to module paths.

2. vendor/_appmap/wrapt/importer.py

   • Adjust the _set_loader and _load_module methods to include logic for individual file instrumentation.

3. _appmap/recorder.py

   • Ensure that file paths are properly registered for recording in addition to modules.
   • Modify Recorder methods to handle events from both modules and individual files.

4. Integration with existing configurations

   • Update any code that parses appmap.yml to recognize and correctly handle individual Python file paths.
   • Ensure backward compatibility with existing appmap.yml configurations that list only modules.

Detailed Implementation

1. _appmap/configuration.py:

   • Modify the find_top_packages to scan for individual .py files and include them in the packages list.
   • Adjust _resolve_relative_to to resolve paths for .py files and validate their existence.
   • Ensure compatibility of file paths alongside module paths in the default_packages and packages properties.

2. _appmap/recorder.py:

   • Update the Recorder class to handle file paths in its recording registry.
   • Ensure the _start_recording and _stop_recording methods correctly initiate and end recording for individual Python files.

3. Other files (init, env, generation, etc.):

   • Adjust relevant methods and classes to support file-path-based instrumentation.
   • Ensure all necessary imports and utilities can handle both module and file paths.

Summary

This update will enable appmap-python to record individual Python files if their paths are specified in appmap.yml. The changes involve modifications in configuration parsing, instrumentation setup, and recorder handling to support the recording of both modules and individual files.

By implementing these changes, users will gain the enhanced ability to record and analyze simpler Python projects or specific Python scripts, improving the flexibility and usability of AppMap.