Upgrade API Documentation to be Python 3 Compatible

[jess-tech-lab]

Proposed change

This PR updates the API document API.md to transition all Python examples from Python 2 to Python 3.10+. The current documentation contains deprecated syntax including print ..., the u' string prefix, and missing byte decoding, which leads to errors in Python 3.

Proposed changes are as follows:

• Byte-to-String Handling: Updated all r.content examples to include .decode('utf-8') to prevent TypeError in Python 3.
• SSL/TLS Configuration: Added explicit verify=False to all example requests to prevent the error certificate verify failed: self-signed certificate since by default Python 3 enforces certificate verification and the API uses a self-signed certificate.
• Syntax Change: Changed print ... to print(...) and removed Python 2 specific unicode prefix u'.

Type of change

• New core framework functionality
• Bugfix (non-breaking change which fixes an issue)
• Code refactoring without any functionality changes
• New or existing module/payload change
• Documentation/localization improvement
• Test coverage improvement
• Dependency upgrade
• Other improvement (best practice, cleanup, optimization, etc)

Checklist

• I've followed the contributing guidelines
• I've run make pre-commit, it didn't generate any changes
• I've run make test, all tests passed locally

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7e8d1dc and ec34e3f.

📒 Files selected for processing (1)

• docs/API.md

---

Summary by CodeRabbit

• Documentation
  • Updated API docs: examples now show disabling SSL verification for local self-signed certificates (with a clear warning not to use this against external/production hosts) and demonstrate decoded/JSON response handling in example requests and outputs.

Walkthrough

Adds a note about disabling SSL warnings for local Nettacker API with self-signed certificates and updates HTTP examples to use verify=False and to parse responses with r.json() or r.text instead of raw r.content.

Changes

Cohort / File(s)	Summary
API Documentation Examples docs/API.md	Added a note explaining disable_warnings(InsecureRequestWarning) and that verify=False is for local/self-signed certs only. Updated HTTP examples to include verify=False. Replaced r.content-based outputs with r.json() or r.text across examples (new scan, session flows, results retrieval, hosts listing, HTML/JSON outputs). Status code checks and overall flows preserved.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the main change: updating API documentation for Python 3 compatibility, which aligns with the described changes to syntax, byte handling, and SSL verification.
Description check	✅ Passed	The description is directly related to the changeset, providing clear details about Python 2 to Python 3 migration including byte decoding, SSL verification, and syntax updates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

docs/API.md (2)

82-82: Prefer r.json() over json.loads(r.content.decode('utf-8')) for JSON responses.

The requests library exposes r.json() which handles decoding and parsing in one step, and r.text for plain decoded responses. Both are the idiomatic Python 3 alternatives throughout the file:

♻️ Suggested simplifications (representative lines; pattern applies to all similar occurrences)

->>> print(json.dumps(json.loads(r.content.decode('utf-8')), sort_keys=True, indent=4))
+>>> print(json.dumps(r.json(), sort_keys=True, indent=4))

->>> r.content.decode('utf-8')
+>>> r.text

->>> print(r.content.decode('utf-8'))
+>>> print(r.text)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/API.md` at line 82, Replace direct decoding and parsing of response
content with the idiomatic requests helpers: where the code uses patterns like
print(json.dumps(json.loads(r.content.decode('utf-8')), sort_keys=True,
indent=4)) (variable r), swap to print(json.dumps(r.json(), sort_keys=True,
indent=4)) for JSON responses and use r.text for plain decoded text; update all
similar occurrences that call json.loads(r.content.decode(...)) to r.json() and
any manual .content.decode(...) usage to r.text.

---

229-244: Set s.verify = False once on the session rather than per-request.

Passing verify=False to every individual s.get() call is repetitive. Since the whole session targets the same self-signed endpoint, disabling verification at the session level is cleaner and consistent with how requests.Session is designed to be used.

♻️ Proposed simplification

 >>> s = requests.session()
+>>> s.verify = False
->>> r = s.get("https://localhost:5000/session/set?key=09877e92c75f6afdca6ae61ad3f53727", verify=False)
+>>> r = s.get("https://localhost:5000/session/set?key=09877e92c75f6afdca6ae61ad3f53727")

Apply the same removal of verify=False to all subsequent s.get() calls in the session sections.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/API.md` around lines 229 - 244, The examples repeatedly pass
verify=False to each s.get call; instead, set the session-level flag once by
assigning s.verify = False immediately after creating the session (after s =
requests.session()) and remove all per-request verify=False arguments from
subsequent calls to s.get (and any other session requests) so the session
consistently uses the disabled verification for the self-signed endpoint.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/API.md`:
- Around line 59-68: Add a brief security note under the "## Requests Structure"
heading explaining that the examples call
disable_warnings(InsecureRequestWarning) and use verify=False which disables TLS
certificate validation, clarifying that this is only for the local Nettacker API
with a self-signed cert and must not be used against external/production hosts;
mention both disable_warnings(InsecureRequestWarning) and verify=False by name
so readers understand which patterns are unsafe for production.

---

Nitpick comments:
In `@docs/API.md`:
- Line 82: Replace direct decoding and parsing of response content with the
idiomatic requests helpers: where the code uses patterns like
print(json.dumps(json.loads(r.content.decode('utf-8')), sort_keys=True,
indent=4)) (variable r), swap to print(json.dumps(r.json(), sort_keys=True,
indent=4)) for JSON responses and use r.text for plain decoded text; update all
similar occurrences that call json.loads(r.content.decode(...)) to r.json() and
any manual .content.decode(...) usage to r.text.
- Around line 229-244: The examples repeatedly pass verify=False to each s.get
call; instead, set the session-level flag once by assigning s.verify = False
immediately after creating the session (after s = requests.session()) and remove
all per-request verify=False arguments from subsequent calls to s.get (and any
other session requests) so the session consistently uses the disabled
verification for the self-signed endpoint.