You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,7 +15,7 @@ Given a folder with code, `inspect4py` will:
15
15
- Extract the hierarchy of directories and files.
16
16
- Extract the requirements used in the software project.
17
17
- Classify which files are tests
18
-
- Classify the main type of software project (script, package, library or service). Only one type is returned as main type (e.g., if a library has the option to be deployed as a service, code_inspector will
18
+
- Classify the main type of software project (script, package, library or service). Only one type is returned as main type (e.g., if a library has the option to be deployed as a service, `inspect4py` will
19
19
- Return a ranking of the different ways in which a a software component can be run, ordered by relevance.
Library to allow users inspect a software project folder (i.e., a directory and its subdirectories) and extract all the most relevant information, such as class, method and parameter documentation, classes (and their methods), functions, etc.
4
4
5
5
## Features
6
6
7
-
Given a folder with code, `code_inspector` will:
7
+
Given a folder with code, `inspect4py` will:
8
8
9
-
- Extract all classes in the code
10
-
- For each class, extract all its methods.
11
-
- For each class, extract all its imported modules and how each module is imported as.
12
-
- For each class and method, extract its documentation, including parameters, and accepted values.
13
-
- Record the control flow of each file.
14
-
- Requirement extraction from imported modules.
15
-
- Extraction of the main method to invoke the software (ongoing work).
16
-
- Extraction of the type of script or library that the code project is (e.g., a package, a service, a library, or a script).
9
+
- Extract all imported modules and how each module is imported as (i.e., whether they are internal or external).
10
+
- Extract all functions in the code, including their documentation, parameters, accepted values, and call list.
11
+
- Extract all classes in the code, with all their methods and respective documentation
12
+
- Extract the control flow of each file.
13
+
- Extract the hierarchy of directories and files.
14
+
- Extract the requirements used in the software project.
15
+
- Classify which files are tests
16
+
- Classify the main type of software project (script, package, library or service). Only one type is returned as main type (e.g., if a library has the option to be deployed as a service, `inspect4py` will
17
+
- Return a ranking of the different ways in which a a software component can be run, ordered by relevance.
17
18
18
-
All metadata is extracted as a JSON file. See the [documentation](https://code-inspector.readthedocs.io/en/latest/output.html) for more details.
19
+
All metadata is extracted as a JSON file. See the [documentation](https://inspect4py.readthedocs.io/en/latest/output.html) for more details.
19
20
20
21
21
22
!!! warning
22
-
`code_inspector` currently works **for Python projects only**. Some of its features (e.g., AST extraction) are only supported for Python 3.x projects.
23
+
`inspect4py` currently works **for Python projects only**. Some of its features (e.g., AST extraction) are only supported for Python 3.x projects.
23
24
24
25
!!! info
25
-
If you experience any issues when using code_inspector, please open an issue on our [GitHub repository](https://github.com/SoftwareUnderstanding/code_inspector/issues).
26
+
If you experience any issues when using inspect4py, please open an issue on our [GitHub repository](https://github.com/SoftwareUnderstanding/inspect4py/issues).
code_inpsector uses [abstract syntax trees (ASTs)](https://en.wikipedia.org/wiki/Abstract_syntax_tree), more specifically
3
+
inspect4py uses [abstract syntax trees (ASTs)](https://en.wikipedia.org/wiki/Abstract_syntax_tree), more specifically
4
4
the [ast](https://docs.python.org/3/library/ast.html) module in Python, generating a tree of objects (per file) whose classes all inherit from [ast.AST](https://docs.python.org/3/library/ast.html#ast.AST).
5
5
6
-
code_inspector parses each of the input file(s) as an ast tree, and walks across them, extracting
6
+
inspect4py parses each of the input file(s) as an ast tree, and walks across them, extracting
7
7
the relevant information, storing it as a JSON file. Furthermore, it also captures the control
8
8
flow of each input file(s), by using another two libraries:
9
9
@@ -16,7 +16,7 @@ flow of each input file(s), by using another two libraries:
16
16
17
17
For parsing the docstrings, we use [docstring_parser](https://pypi.org/project/docstring-parser/), which has support for ReST, Google, and Numpydoc-style docstrings. Some (basic) tests done using this library can be found at [here](./test_docstring_parser/).
18
18
19
-
It also usese [Pigar](https://github.com/damnever/pigar) for generating automatically the requirements of a given repository. This is an optional funcionality. In order to activate the argument (-r) has to be indicated when we run the code_inspector.
19
+
It also usese [Pigar](https://github.com/damnever/pigar) for generating automatically the requirements of a given repository. This is an optional funcionality. In order to activate the argument (-r) has to be indicated when we run inspect4py.
20
20
21
21
## Install
22
22
@@ -32,14 +32,20 @@ Then, prepare a virtual Python3 enviroment and install the required packages.
32
32
33
33
`pip install -r requirements.txt`
34
34
35
-
- Dependencies:
36
-
- cdmcfparser==2.3.2
37
-
- docstring_parser==0.7
38
-
- astor
39
-
- graphviz
40
-
- Click
41
-
- setuptools == 54.2.0
42
-
- json2html
35
+
Dependencies:
36
+
```
37
+
cdmcfparser
38
+
docstring_parser==0.7
39
+
astor
40
+
graphviz
41
+
click
42
+
pigar
43
+
setuptools==54.2.0
44
+
json2html
45
+
configparser
46
+
```
47
+
48
+
If you want to run the evaluations, do not forget to add `pandas` to the previous set
43
49
44
50
### Installation through Docker
45
51
@@ -48,28 +54,28 @@ First, you will need to have [Docker](https://docs.docker.com/get-started/) inst
Copy file name to clipboardExpand all lines: docs/output.md
+57-17Lines changed: 57 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,14 +1,15 @@
1
-
* Results are stored by default inside the **OutputDir** directory, which is created automatically, if it is does not exits. Users have also the possibility to indicate their own directory name.
1
+
`inspect4py` results are stored by default inside an `OutputDir` directory, which is created automatically if it is does not exits. Users have also the possibility to indicate their own directory name.
2
2
3
-
* If the input is a **file**, the tool will create automatically two subdirectories inside **OuptuDir**:
4
-
- **JsonFiles** directory: with a json file (with the name of the file + ".json") of the information extracted
5
-
- **ControlFlow** directory: with one or two (depending on the FLAG_PNG) Control Flow files will be created
3
+
If the input is a **file**, the tool will automatically create two subdirectories inside `OuptuDir`:
6
4
7
-
* If the input is a **directory**, the tool will create the previous directories (**JsonFiles** and **ControlFlow**) but per **directory** and its **subdirectories** instead, under **OutputDir**, storing all the information extracted per file found in each directory and/or subdirectory. The **OutputDir** directory will have the same subdirectory structure as the input directory given by the user. Furthermore, in order to facilitate the inspection of all the features extracted for a given directory (and its subdirectories), we have aggreagated all the previous json information in a **single json file** stored at **OutputDir/DirectoryInfo.json**.In other words, **OutputDir/DirectoryInfo.json**, represents all the features extracted of all files found in a given directory (and its subdirectories).
5
+
-**JsonFiles** directory: with a JSON file (with the name of the file + ".json") of the information extracted
6
+
-**ControlFlow** directory: containing one or two control flow files depending on the execution options.
8
7
9
-
### JSON FILE
8
+
If the input is a **directory**, inspect4py will create the **JsonFiles** and **ControlFlow** directories for each **directory** in the original repository, under `OutputDir`. These folders store all the information extracted per file. The `OutputDir` directory will have the same subdirectory structure as the input directory given by the user. In order to ease the inspection of all the features extracted for a given directory (and its subdirectories) we have aggregated all generated json information in a **single JSON file** stored at `OutputDir/DirectoryInfo.json`.In other words, `OutputDir/DirectoryInfo.json`, represents all the features extracted of all files found in a given directory (and its subdirectories).
10
9
11
-
* File features:
10
+
## JSON file format
11
+
12
+
### File features:
12
13
```
13
14
- file:
14
15
- path: <file_name>.py
@@ -20,7 +21,7 @@
20
21
- full
21
22
22
23
```
23
-
* Dependencies features:
24
+
### Dependency features:
24
25
```
25
26
- dependencies: (list of dependencies)
26
27
-dep_<0>:
@@ -34,7 +35,7 @@
34
35
-dep_<1>:
35
36
- ...
36
37
```
37
-
* Classes features:
38
+
### Class features:
38
39
```
39
40
- classes: (list of classes)
40
41
-<class_name>:
@@ -84,8 +85,7 @@
84
85
- ...
85
86
```
86
87
87
-
88
-
* Function features:
88
+
### Function features:
89
89
90
90
```
91
91
- functions: (list of functions found within the class):
@@ -123,24 +123,62 @@
123
123
-<function_name>:
124
124
- ...
125
125
```
126
-
* ControlFlow features:
126
+
###ControlFlow features:
127
127
```
128
128
- controlflow:
129
129
- cfg: Path of the cfg as a txt
130
130
- png: Path of the cfg as a PNG
131
-
131
+
```
132
+
### Test information:
133
+
```
134
+
"tests": [
135
+
{
136
+
"type": "test",
137
+
"run": "python path_to_test/test.py",
138
+
"has_structure": "main", # (if the test has a main function)
139
+
"mentioned_in_readme": false # (if the test is not mentioned
140
+
the main README file)
141
+
},
142
+
143
+
],
144
+
```
145
+
### Software invocation:
146
+
```
147
+
"software_invocation": [
148
+
{
149
+
"run": [
150
+
"somef"
151
+
],
152
+
"type": "package", # Types include package, library, service,
153
+
and script
154
+
"installation": "pip install somef",
155
+
"ranking": 1 # Relevance sorted in ascending order
156
+
},
157
+
{
158
+
"type": "script",
159
+
"run": "python path_to_script/script.py",
160
+
"has_structure": "main",
161
+
"mentioned_in_readme": false,
162
+
"ranking": 2
163
+
},
164
+
],
165
+
```
166
+
### Software type:
167
+
```
168
+
"software_type": "package"
132
169
```
133
170
## Example
134
171
135
-
The easiest example is to run `code_inspector` against itself:
172
+
The easiest example is to run `inspect4py` against itself:
Results of this run include a JSON file and a control flow file
141
178
142
-
If no output directory is specified, `code_inspector` will place the documentation in **OuptuDir**, including a JSON File and a control flow file for each code file found in the analyzed directory.
179
+
If no output directory is specified, `inspect4py` will place the documentation in **OuptuDir**, including a JSON File and a control flow file for each code file found in the analyzed directory.
143
180
181
+
<!--
144
182
## Visualizing results
145
183
146
184
We include visualization tools to explore the results in an easy manner. Below we show some visualizations of the results for `code_inspector` code:
The tool can be executed to inspect a file, or all the files of a given directory (and its subdirectories).
1
+
Inspect4py can be executed to inspect a file, or all the files of a given directory (and its subdirectories).
2
2
For example, it can be used to inspect all the python files of a given GitHub repository (that has been previously cloned locally).
3
3
4
-
The tool by default stores the results in the "OutputDir" directory, but users can specify their own directory name by using -o or --output flags.
5
-
6
-
And the tools allows users to specify if control flow figures will be generated or not. By default they wont be generated. To indicate the generation of control flow figures, users should use -f or --fig.
4
+
The tool by default stores the results in the "OutputDir" directory, but users can specify their own directory name by using `-o` or `--output` flags.
7
5
6
+
And the tools allows users to specify if control flow figures will be generated or not. By default they wont be generated. To indicate the generation of control flow figures, users should use `-f` or `--fig`.
0 commit comments