Add inspection module to replace print_routes #1661

CaselIT · 2020-02-02T10:15:09Z

Summary of Changes

Create an inspection module to replace the print_route script.
This was inspired by the discussion about #1435 but has evolved in a inspection module that can obtain information regarding the application and create a pretty print of it.

The public interface of the inspection module has different functions that return information regarding an application.
There is a main function to inspect the entire application (routes, middleware, static_routes, sinks and error_handlers) and also individual functions for each.
The returned information are instance of classes (or list of them) which can return a pretty print, since this is more extensible than just a string.
There is also the ability to register inspection of different route class implementations by using a decorator on a inspection function that handles a particular type of router.

This is the output of a sample application

Falcon App (WSGI)
• Routes:
    ⇒ /foo - MyResponder:
       ├── DELETE - on_delete
       ├── GET - on_get
       └── POST - on_post
    ⇒ /foo/{id} - MyResponder:
       ├── DELETE - on_delete_id
       ├── GET - on_get_id
       └── POST - on_post_id
    ⇒ /bar - OtherResponder:
       ├── DELETE - on_delete_id
       ├── GET - on_get_id
       └── POST - on_post_id
• Middleware (Middleware are independent):
    → MyMiddleware.process_request

      ↣ MyMiddleware.process_resource
        ↣ OtherMiddleware.process_resource

            ├── Process responder

        ↢ OtherMiddleware.process_response
      ↢ CORSMiddleware.process_response
• Static routes:
    ↦ /tests/ C:\Users\Federico\Dev\GitHub\falcon\tests [C:\Users\Federico\Dev\GitHub\falcon\tests\conftest.py]
    ↦ /falcon/ C:\Users\Federico\Dev\GitHub\falcon\falcon
• Sinks:
    ⇥ /sink_cls SinkClass
    ⇥ /sink_fn sinkFn
• Error handlers:
    ⇜ RuntimeError my_runtime_handler

A more verbose output is

View

Falcon App (WSGI)
• Routes:
    ⇒ /foo - MyResponder (c:\users\federico\dev\github\falcon\try_print.py:19):
       ├── DELETE - on_delete (c:\users\federico\dev\github\falcon\try_print.py:26)
       ├── GET - on_get (c:\users\federico\dev\github\falcon\try_print.py:20)
       ├── POST - on_post (c:\users\federico\dev\github\falcon\try_print.py:23)
       ├── OPTIONS - options_responder (c:\users\federico\dev\github\falcon\falcon\responders.py:84)
       ├── CONNECT - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── HEAD - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── PATCH - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── PUT - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── TRACE - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── CHECKIN - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── CHECKOUT - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── COPY - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── LOCK - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── MKCOL - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── MOVE - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── PROPFIND - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── PROPPATCH - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── REPORT - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── UNCHECKIN - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── UNLOCK - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── UPDATE - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       └── VERSION-CONTROL - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
    ⇒ /foo/{id} - MyResponder (c:\users\federico\dev\github\falcon\try_print.py:19):
       ├── DELETE - on_delete_id (c:\users\federico\dev\github\falcon\try_print.py:35)
       ├── GET - on_get_id (c:\users\federico\dev\github\falcon\try_print.py:29)
       ├── POST - on_post_id (c:\users\federico\dev\github\falcon\try_print.py:32)
       ├── OPTIONS - options_responder (c:\users\federico\dev\github\falcon\falcon\responders.py:84)
       ├── CONNECT - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── HEAD - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── PATCH - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── PUT - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── TRACE - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── CHECKIN - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── CHECKOUT - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── COPY - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── LOCK - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── MKCOL - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── MOVE - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── PROPFIND - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── PROPPATCH - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── REPORT - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── UNCHECKIN - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── UNLOCK - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── UPDATE - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       └── VERSION-CONTROL - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
    ⇒ /bar - OtherResponder (c:\users\federico\dev\github\falcon\try_print.py:39):
       ├── DELETE - on_delete_id (c:\users\federico\dev\github\falcon\try_print.py:35)
       ├── GET - on_get_id (c:\users\federico\dev\github\falcon\try_print.py:29)
       ├── POST - on_post_id (c:\users\federico\dev\github\falcon\try_print.py:32)
       ├── OPTIONS - options_responder (c:\users\federico\dev\github\falcon\falcon\responders.py:84)
       ├── CONNECT - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── HEAD - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── PATCH - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── PUT - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── TRACE - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── CHECKIN - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── CHECKOUT - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── COPY - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── LOCK - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── MKCOL - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── MOVE - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── PROPFIND - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── PROPPATCH - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── REPORT - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── UNCHECKIN - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── UNLOCK - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       ├── UPDATE - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
       └── VERSION-CONTROL - method_not_allowed (c:\users\federico\dev\github\falcon\falcon\responders.py:59)
• Middleware (Middleware are independent):
    → MyMiddleware.process_request

      ↣ MyMiddleware.process_resource
        ↣ OtherMiddleware.process_resource

            ├── Process responder

        ↢ OtherMiddleware.process_response
      ↢ CORSMiddleware.process_response
    - Middlewares classes:
        ↣ CORSMiddleware (c:\users\federico\dev\github\falcon\falcon\middlewares.py:2):
           └── process_response (c:\users\federico\dev\github\falcon\falcon\middlewares.py:3)
        ↣ MyMiddleware (c:\users\federico\dev\github\falcon\try_print.py:73):
           ├── process_request (c:\users\federico\dev\github\falcon\try_print.py:74)
           └── process_resource (c:\users\federico\dev\github\falcon\try_print.py:77)
        ↣ OtherMiddleware (c:\users\federico\dev\github\falcon\try_print.py:83):
           ├── process_resource (c:\users\federico\dev\github\falcon\try_print.py:87)
           └── process_response (c:\users\federico\dev\github\falcon\try_print.py:90)
• Static routes:
    ↦ /tests/ C:\Users\Federico\Dev\GitHub\falcon\tests [C:\Users\Federico\Dev\GitHub\falcon\tests\conftest.py]
    ↦ /falcon/ C:\Users\Federico\Dev\GitHub\falcon\falcon
• Sinks:
    ⇥ /sink_cls SinkClass (c:\users\federico\dev\github\falcon\try_print.py:57)
    ⇥ /sink_fn sinkFn (c:\users\federico\dev\github\falcon\try_print.py:53)
• Error handlers:
    ⇜ Exception _python_error_handler (c:\users\federico\dev\github\falcon\falcon\app.py:894)
    ⇜ HTTPError _http_error_handler (c:\users\federico\dev\github\falcon\falcon\app.py:891)
    ⇜ HTTPStatus _http_status_handler (c:\users\federico\dev\github\falcon\falcon\app.py:888)
    ⇜ RuntimeError my_runtime_handler (c:\users\federico\dev\github\falcon\try_print.py:66)

This is still very much still a proof of concept wip, with documentation and test missing. I wanted to open this PR to get feedback on this.

The main items that are missing are:

verify that everything work with an async app
tests
documentation on it. I think it would be useful if we include the output of the inspection in the example documentation to better visualize the configuration of the example

Related Issues

This fixes #1435

Pull Request Checklist

This is just a reminder about the most common mistakes. Please make sure that you tick all appropriate boxes. But please read our contribution guide at least once; it will save you a few review cycles!

If an item doesn't apply to your pull request, check it anyway to make it apparent that there's nothing to do.

If you have any questions to any of the points above, just submit and ask! This checklist is here to help you, not to deter you from contributing!

PR template inspired by the attrs project.

…f falcon applications

…mmand

setup.py

codecov · 2020-02-25T19:42:07Z

Codecov Report

❗ No coverage uploaded for pull request base (master@98929d5). Click here to learn what that means.
The diff coverage is 100%.

@@           Coverage Diff            @@
##             master   #1661   +/-   ##
========================================
  Coverage          ?    100%           
========================================
  Files             ?      49           
  Lines             ?    3895           
  Branches          ?     606           
========================================
  Hits              ?    3895           
  Misses            ?       0           
  Partials          ?       0

Impacted Files	Coverage Δ
falcon/status_codes.py	`100% <100%> (ø)`
falcon/inspect.py	`100% <100%> (ø)`
falcon/asgi/structures.py	`100% <100%> (ø)`
falcon/media/multipart.py	`100% <100%> (ø)`
falcon/routing/compiled.py	`100% <100%> (ø)`
falcon/asgi/request.py	`100% <100%> (ø)`

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 98929d5...6d630e3. Read the comment docs.

CaselIT · 2020-02-28T21:53:23Z

The code and the tests should be done.
The documentation is still missing. I was thinking of adding a new documentation page with a brief explanation of the module and an example output similar to the one in this page.
Also maybe mention it in some tutorial examples, like where it's adding the roues and the one on the middleware?

codecov-io · 2020-02-28T21:59:07Z

Codecov Report

Merging #1661 into master will not change coverage by %.
The diff coverage is n/a.

@@            Coverage Diff            @@
##            master     #1661   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           49        49           
  Lines         3928      3928           
  Branches       611       611           
=========================================
  Hits          3928      3928

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 02d7829...02d7829. Read the comment docs.

CaselIT · 2020-02-29T12:06:35Z

I've added a new documentation file for the inspect module and updated the quickstart and tutorial files to introduce the inspect module.

I think this is ready for a review

…on, fix pep

setup.py

kgriffs

I did a quick test with suffixed responders and they were displayed correctly. Overall the patch looks sound. I still need to spend some time going through the details.

CaselIT · 2020-03-03T06:54:05Z

Take your time, it ended up being quite large 👍

The suffixed responders are not treated differently than the normal ones, but the name of the function is correctly printed, like "on_get_with_suffix", but maybe there should be an attribute in the route method class that contains the suffix?

Also I was wondering if we should separate the internal routers from the source info print. Now both are under the verbose flag. Maybe we could add an "internal" flag?

kgriffs · 2020-03-04T15:57:30Z

The suffixed responders are not treated differently than the normal ones, but the name of the function is correctly printed, like "on_get_with_suffix", but maybe there should be an attribute in the route method class that contains the suffix?

TBH I think it looks good as-is.

Also I was wondering if we should separate the internal routers from the source info print. Now both are under the verbose flag. Maybe we could add an "internal" flag?

That would be great, actually.

CaselIT · 2020-03-04T20:19:11Z

@kgriffs I've split the internal and the verbose options.

CaselIT

Thanks for the update. Just noticed a typo

CaselIT · 2020-03-27T17:19:56Z

docs/api/inspect.rst

-The output would be:
-
-.. code::
+    # my_module exposes tha application as a variable named "app"


fixed, thx!

kgriffs · 2020-03-28T00:38:13Z

Hope you don't mind my tweaks... just trying to polish up the prose a bit.

CaselIT

just a small comment

CaselIT · 2020-03-28T00:51:13Z

falcon/inspect.py


    Returns:
-        List[StaticRouteInfo]: The list of static routes of the application.
+        List[StaticRouteInfo]: The list of static routes that have


A list? as above?

CaselIT · 2020-03-28T00:51:41Z

falcon/inspect.py


    Returns:
-        List[SinkInfo]: The list of sinks of the application.
+        List[SinkInfo]: The list of sinks used by the application.


A list? as above?

CaselIT · 2020-03-28T00:51:49Z

falcon/inspect.py


    Returns:
-        List[ErrorHandlerInfo]: The list of error handlers of the application.
+        List[ErrorHandlerInfo]: The list of error handlers used by the


A list? as above?

CaselIT · 2020-03-28T00:53:53Z

Hope you don't mind my tweaks... just trying to polish up the prose a bit.

No, not at all. I'm not very good with the documentation :(

CaselIT · 2020-03-30T21:10:10Z

Nice!

CaselIT added 10 commits February 1, 2020 22:13

feat(inspec): add inspect module to support programmatic inspection o…

25a83f6

…f falcon applications

refactor(print_routes): use the new inspect module in print_routes co…

082e318

…mmand

feat(inspect): add inspection of app, static routes and sinks

d41fb46

refactor(print_routes): use inspect_app by default

d7181bc

feat(inspect): add support for error handlers inspection

75920c1

feat(inspect): add support for middleware inspection

90574bd

chore(inspect): cleanup code

2608a10

refactor(inspect): cleanup code, add types

18a7697

style(inspect): fix quote style

23fbefa

refactor(inspect): move inspect module out of util. Rename script

bf9242d

CaselIT mentioned this pull request Feb 3, 2020

Improve falcon-print-routes tool #1435

Closed

feat(inspect): use a visitor to transform the info class to string

403bd6c

vytas7 reviewed Feb 24, 2020

View reviewed changes

setup.py Outdated Show resolved Hide resolved

CaselIT added 3 commits February 24, 2020 22:15

Merge branch 'master' into inspect-api

30607ca

test(inspect): add tests to inspect_app command line

eb13d02

chore: add license, fix pep

0aa87b9

test: fix import error by adding __init__ in test module while testing

455b857

CaselIT force-pushed the inspect-api branch from d3eb26a to 455b857 Compare February 25, 2020 20:13

CaselIT added 7 commits February 25, 2020 23:18

test: add initial inspect tests

182c285

test: fix broken tests

53f8dc3

test: more tests

0461afb

test: continue adding test to string visitor

860ae7a

test: complete tests of inspect module

98929d5

Merge branch 'master' into inspect-api

8c7b370

chore: add missing test and restore previous cmd alias

6d630e3

CaselIT marked this pull request as ready for review February 28, 2020 21:53

docs(inspect): add inspect documentation

b32e501

chore: ignore routes without a responder. Improve middleware str output

1bbc4f4

CaselIT requested a review from vytas7 February 29, 2020 11:49

CaselIT and others added 2 commits February 29, 2020 13:55

chore: use the falcon-inspect-app in the doc, improve module resoluti…

c67319c

…on, fix pep

Merge branch 'master' into inspect-api

be0198c

kgriffs reviewed Mar 3, 2020

View reviewed changes

setup.py Outdated Show resolved Hide resolved

kgriffs reviewed Mar 3, 2020

View reviewed changes

Merge branch 'master' into inspect-api

7dc8f97

CaselIT added 3 commits March 4, 2020 20:36

chore: deprecate print routes command

2519300

refactor: split inspect and verbose

61cd320

chore: add missing test

e69f92d

docs: document internal flag

2d7a272

CaselIT requested a review from kgriffs March 4, 2020 20:32

kgriffs and others added 4 commits March 16, 2020 22:16

Merge branch 'master' into inspect-api

17b939a

Merge branch 'master' into inspect-api

23bad19

fix(mypy): fix mypy errors

bd0a74d

doc(inspect.rst): Minor edits for organization and clarity

051d05b

CaselIT commented Mar 27, 2020

View reviewed changes

kgriffs added 2 commits March 27, 2020 18:34

doc(inspect): Tweak docstrings

ab61a58

doc(inspect.rst): Fix typo

8bba95d

CaselIT commented Mar 28, 2020

View reviewed changes

doc(inspect): "The" ==> "A"

02d7829

kgriffs merged commit b437e5e into falconry:master Mar 30, 2020

CaselIT deleted the inspect-api branch March 30, 2020 21:10

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add inspection module to replace print_routes #1661

Add inspection module to replace print_routes #1661

CaselIT commented Feb 2, 2020 •

edited

Loading

codecov bot commented Feb 25, 2020 •

edited

Loading

CaselIT commented Feb 28, 2020

codecov-io commented Feb 28, 2020 •

edited by codecov bot

Loading

CaselIT commented Feb 29, 2020

kgriffs left a comment

CaselIT commented Mar 3, 2020 •

edited

Loading

kgriffs commented Mar 4, 2020

CaselIT commented Mar 4, 2020

CaselIT left a comment

CaselIT Mar 27, 2020

kgriffs Mar 28, 2020

kgriffs commented Mar 28, 2020

CaselIT left a comment

CaselIT Mar 28, 2020

CaselIT Mar 28, 2020

CaselIT Mar 28, 2020

CaselIT commented Mar 28, 2020

CaselIT commented Mar 30, 2020

Add inspection module to replace print_routes #1661

Add inspection module to replace print_routes #1661

Conversation

CaselIT commented Feb 2, 2020 • edited Loading

Summary of Changes

Related Issues

Pull Request Checklist

codecov bot commented Feb 25, 2020 • edited Loading

Codecov Report

CaselIT commented Feb 28, 2020

codecov-io commented Feb 28, 2020 • edited by codecov bot Loading

Codecov Report

CaselIT commented Feb 29, 2020

kgriffs left a comment

Choose a reason for hiding this comment

CaselIT commented Mar 3, 2020 • edited Loading

kgriffs commented Mar 4, 2020

CaselIT commented Mar 4, 2020

CaselIT left a comment

Choose a reason for hiding this comment

CaselIT Mar 27, 2020

Choose a reason for hiding this comment

kgriffs Mar 28, 2020

Choose a reason for hiding this comment

kgriffs commented Mar 28, 2020

CaselIT left a comment

Choose a reason for hiding this comment

CaselIT Mar 28, 2020

Choose a reason for hiding this comment

CaselIT Mar 28, 2020

Choose a reason for hiding this comment

CaselIT Mar 28, 2020

Choose a reason for hiding this comment

CaselIT commented Mar 28, 2020

CaselIT commented Mar 30, 2020

CaselIT commented Feb 2, 2020 •

edited

Loading

codecov bot commented Feb 25, 2020 •

edited

Loading

codecov-io commented Feb 28, 2020 •

edited by codecov bot

Loading

CaselIT commented Mar 3, 2020 •

edited

Loading