Replace deprecated inspect.formatargspec with inspect.signature

[hugovk]

inspect.formatargspec is deprecated:

Deprecated since version 3.5: Use signature() and Signature Object, which provide a better introspecting API for callables.

https://docs.python.org/3/library/inspect.html#inspect.formatargspec

python/cpython#28618

[codecov-commenter]

Codecov Report

Merging #2507 (1d47590) into develop (098cc25) will decrease coverage by 0.00%.
The diff coverage is 100.00%.

@@             Coverage Diff             @@
##           develop    #2507      +/-   ##
===========================================
- Coverage    95.30%   95.30%   -0.01%     
===========================================
  Files           60       60              
  Lines        12262    12261       -1     
===========================================
- Hits         11686    11685       -1     
  Misses         576      576              

Impacted Files	Coverage Δ
botocore/docs/method.py	100.00% <100.00%> (ø)

---

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 098cc25...1d47590. Read the comment docs.

[nateprewitt]

Thanks for the PR @hugovk! We'd started some of this work but weren't sure what the impact of this change is on documentation generation. I think the only outstanding check is validating we're not adding additional signature footprint (specifically with the inclusion of self) in this change.

I believe the move to Signature, and no longer using [1:] for args, may be an issue.

[mgorny]

Ping. This is now breaking botocore on Python 3.11, where inspect.formatargspec() was removed.

[mgorny]

I've submitted #2673 as a little more elaborate approach that preserves the current behavior of skipping "self" (or more precisely, the first positional parameter). I hope you don't mind me modifying your code.

[hugovk]

Absolutely not, go for it!

[nateprewitt]

Thanks @mgorny, we’re waiting for the last reformatting PR to get merged in the next week or two. Then we plan to drop Python 3.6 on May 30th, at which point we’ll merge this and start testing on the 3.11dev build.

[mgorny]

Thanks. It seems that I need to work on it some more but I should finish it today.

[dlm6693]

@hugovk thank you for submitting this original PR and thank you @mgorny for following up with the impending release of 3.11! However, we will be merging this original one as inspect.signature implicitly does NOT include self as an argument, which is the desired behavior for botocore doc generation. I tested this specific function as well as generated diffs for many of our service docs both before and after implementing this change and found that there weren't any

[dlm6693]

@mgorny these are a few manual tests that I ran:

import inspect
from botocore.loaders import Loader

class Foo:
    def test(self, a, b):
        pass

f = Foo()
inspect.signature(f.test)
<Signature (a, b)>

l = Loader()
inspect.signature(l._potential_locations)
<Signature (name=None, must_exist=False, is_dir=False)>

Note that self is not included in either Signature object