Add base module type stubs #45
Conversation
WalkthroughThis update introduces a comprehensive set of Python type stub ( Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant API
participant TypeChecker
User->>API: Imports or uses netius.base components
API->>TypeChecker: Provides .pyi stubs for static analysis
TypeChecker-->>User: Reports type errors, autocompletion, and interface info
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🧰 Additional context used🪛 Pylint (3.3.7)src/netius/test/base/stubs.py[refactor] 1-1: Useless option value for '--disable', 'C0326' was removed from pylint, see pylint-dev/pylint#3577. (R0022) [refactor] 1-1: Useless option value for '--disable', 'C0330' was removed from pylint, see pylint-dev/pylint#3571. (R0022) 🔇 Additional comments (3)
✨ Finishing Touches
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Pull Request Overview
Adds stub (.pyi) files to provide type definitions for the base modules of the netius package.
- Introduce Python stubs for utility functions, streaming, services, servers, polling, observables, containers, common infrastructure, clients, and agents.
- Define classes, method signatures, and constants to improve type checking and IDE support.
- Wire up inter-module references through imports of base classes and components.
Reviewed Changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| src/netius/base/util.pyi | Add utility function stubs (camel_to_underscore, verify). |
| src/netius/base/stream.pyi | Define Stream constants and method signatures. |
| src/netius/base/service.pyi | Add Service class signature and on_socket_c hook. |
| src/netius/base/server.pyi | Add Server and DatagramServer stubs with serve. |
| src/netius/base/poll.pyi | Stub out Poll base and its implementations. |
| src/netius/base/observer.pyi | Add Observable events and lifecycle methods. |
| src/netius/base/container.pyi | Define Container and ContainerServer interfaces. |
| src/netius/base/common.pyi | Add threading and loop-factory utility stubs. |
| src/netius/base/client.pyi | Stub Client and DatagramClient patterns. |
| src/netius/base/agent.pyi | Add Agent, ClientAgent, and ServerAgent. |
Comments suppressed due to low confidence (5)
src/netius/base/server.pyi:12
- Likely a typo:
cer_fileshould becert_fileto match the convention for certificate file names.
cer_file: str | None
src/netius/base/common.pyi:1
- Several stubs reference a
Baseclass imported from.common, butcommon.pyidoes not defineBase. You should add aclass Base: ...stub or adjust imports to use the correct symbol.
from typing import Any, Callable, Iterable
src/netius/base/container.pyi:4
StreamServeris not defined inserver.pyi. Update the import to the correct class name (e.g.,Server) or add aStreamServerstub inserver.pyi.
from .server import StreamServer
src/netius/base/server.pyi:3
Baseis imported from.commonbut not defined incommon.pyi. Add aBasestub or correct the import target.
from .common import Base
src/netius/base/client.pyi:3
Baseis imported here but missing fromcommon.pyi. Either defineBaseincommon.pyior remove it from this import.
from .common import Base, BaseThread
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
src/netius/base/service.pyi (2)
6-16: Refineporttype to reflect actual usage.Currently
port: Any | None; if this represents a numeric port, considerint | Nonefor stronger typing.
31-32: Strengthenon_socket_cparameter types.You have
address: Any—if it’s always a(host, port)pair, considertuple[str, int].src/netius/base/poll.pyi (1)
30-87: Reduce duplication across platform‐specific subclasses.Since each subclass redefines the same signatures, consider using a shared Protocol or mixin to DRY up these stubs.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (10)
src/netius/base/agent.pyi(1 hunks)src/netius/base/client.pyi(1 hunks)src/netius/base/common.pyi(1 hunks)src/netius/base/container.pyi(1 hunks)src/netius/base/observer.pyi(1 hunks)src/netius/base/poll.pyi(1 hunks)src/netius/base/server.pyi(1 hunks)src/netius/base/service.pyi(1 hunks)src/netius/base/stream.pyi(1 hunks)src/netius/base/util.pyi(1 hunks)
🔇 Additional comments (23)
src/netius/base/util.pyi (1)
1-4: Stub signatures are accurate. Thecamel_to_underscoreandverifydeclarations correctly express parameter types, default ellipses, and return types for improved editor and type‐checker support.src/netius/base/server.pyi (3)
1-14: Server attribute annotations are consistent. The importedAnyandMappingtypes cover the socket and info fields, and the attributes (socket,host,port, etc.) match expected runtime members.
16-40:servemethod signature is comprehensive. All parameters for networking, SSL, and runtime options are clearly typed, enabling precise IDE and static‐analysis support.
42-48: DatagramServer stubs align with implementation. The read/write/error list methods and overloadedservesignature correctly mirror expected callbacks.src/netius/base/agent.pyi (3)
1-5: Imports and base class linkage are correct.ObservableandClientare properly imported to establish class hierarchies.
6-11:Agentlifecycle methods are well-typed. Both class and instance cleanup/destruction methods are declared with correct signatures.
12-19:ClientAgentstubs are precise. The_clientsmapping and theget_client_sfactory method return the properClienttype.src/netius/base/stream.pyi (2)
1-8: Stream constants and imports are solid. TheOPEN,CLOSED, andPENDINGannotations plus theAnyandObservableimports form a clear foundation.
9-22:Streaminterface is complete. State attributes and lifecycle methods (open,close,reset, etc.) are all properly declared for static typing.src/netius/base/observer.pyi (2)
1-5:Observableimports and event dict type are correct. UsingCallable[..., Any]for handlers covers all callback signatures.
6-14: Event management methods are fully typed. Thebind,unbind,unbind_all, andtriggersignatures accurately reflect the intended API.src/netius/base/container.pyi (3)
1-5: Verify PEP604 union usage and Python version compatibility.You’re using
Base | Noneandlist[Base](PEP604 syntax) in a stub file—ensure your build and type‐checking toolchain targets Python 3.10+ or that your stubs are processed in a forward‐annotation context.
6-26: Container interface stub looks solid.All lifecycle and collection methods are clearly annotated, and required imports are in scope.
28-35: ContainerServer stub is consistent.Inheritance from
StreamServerand theadd_basesignature align withContainer.src/netius/base/service.pyi (1)
18-30: Service constructor stub is clear.Parameters and defaults are well‐annotated. No further issues spotted.
src/netius/base/client.pyi (4)
1-3: Imports look good.
Any,Base, andBaseThreadare correctly imported for use below.
5-7: Class‐level client cache stub is fine.
8-29: Potential typo inconnectsignature.The parameter
cer_filemay be intended ascert_file. Please verify the underlying implementation or rename for clarity.
31-33: DatagramClient stub is straightforward.src/netius/base/common.pyi (3)
1-3: Imports and typing support are appropriate.
4-9:BaseThreadstub is correct.
10-49: Core event‐loop and loop‐management stubs look comprehensive.src/netius/base/poll.pyi (1)
3-29: BasePollinterface stub is solid.
| from typing import Any | ||
|
|
||
| from .observer import Observable | ||
| from .transport import Transport | ||
|
|
There was a problem hiding this comment.
Missing stub for transport.
You import Transport from .transport but no transport.pyi is included in this PR. Please confirm that a stub exists for this module or add it here.
🤖 Prompt for AI Agents
In src/netius/base/service.pyi around lines 1 to 5, you import Transport from
.transport but there is no transport.pyi stub file included in this PR. Verify
if transport.pyi exists in the codebase; if it does not, create a transport.pyi
stub file defining the Transport class or relevant types to ensure proper type
checking and completeness of type stubs.
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
src/netius/test/base/stubs.py (1)
69-71: Enhance test reporting and fix formatting.Consider improving the test method to provide better failure context and fix the missing newline:
def test_stubtest(self): for module in self.MODULES: - self._run_stubtest(module) + with self.subTest(module=module): + self._run_stubtest(module) +Using
subTestwill provide clearer failure reporting when specific modules fail stubtest validation.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/netius/test/base/stubs.py(1 hunks)
🧰 Additional context used
🪛 Pylint (3.3.7)
src/netius/test/base/stubs.py
[refactor] 1-1: Useless option value for '--disable', 'C0326' was removed from pylint, see pylint-dev/pylint#3577.
(R0022)
[refactor] 1-1: Useless option value for '--disable', 'C0330' was removed from pylint, see pylint-dev/pylint#3571.
(R0022)
🪛 GitHub Actions: Main Workflow
src/netius/test/base/stubs.py
[error] 1-1: Test failure detected in this file during pytest run.
🔇 Additional comments (2)
src/netius/test/base/stubs.py (2)
1-33: LGTM! Standard header and appropriate imports.The file header follows standard conventions and the imports are appropriate for subprocess-based testing.
🧰 Tools
🪛 Pylint (3.3.7)
[refactor] 1-1: Useless option value for '--disable', 'C0326' was removed from pylint, see pylint-dev/pylint#3577.
(R0022)
[refactor] 1-1: Useless option value for '--disable', 'C0330' was removed from pylint, see pylint-dev/pylint#3571.
(R0022)
🪛 GitHub Actions: Main Workflow
[error] 1-1: Test failure detected in this file during pytest run.
36-48: LGTM! Well-structured test class and comprehensive module list.The module list appropriately covers all the base modules mentioned in the PR objectives.
| def _run_stubtest(self, module: str) -> None: | ||
| result = subprocess.run( | ||
| [ | ||
| sys.executable, | ||
| "-m", | ||
| "mypy.stubtest", | ||
| module, | ||
| "--mypy-config-file", | ||
| "/dev/null", | ||
| "--ignore-missing-stub", | ||
| "--allowlist", | ||
| "/dev/null", | ||
| ], | ||
| stdout=subprocess.PIPE, | ||
| stderr=subprocess.STDOUT, | ||
| text=True, | ||
| ) | ||
| self.assertEqual(result.returncode, 0, result.stdout) | ||
|
|
||
| def test_stubtest(self): | ||
| for module in self.MODULES: | ||
| self._run_stubtest(module) |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Investigate the pipeline failure root cause.
The pipeline failure suggests that stubtest is failing during execution. This could be due to:
- Platform compatibility issues (addressed above)
- Missing
mypydependency in the test environment - Actual issues with the stub files themselves
Run this script to verify the stub files and dependencies:
🏁 Script executed:
#!/bin/bash
# Check if mypy and stubtest are available
python -m pip list | grep mypy || echo "mypy not installed"
# Check if the stub files exist
for module in agent client common container observer poll server service stream util; do
if [ -f "src/netius/base/${module}.pyi" ]; then
echo "✓ ${module}.pyi exists"
else
echo "✗ ${module}.pyi missing"
fi
done
# Try running stubtest on one module to see the specific error
python -m mypy.stubtest netius.base.common --ignore-missing-stub 2>&1 || echo "stubtest failed"Length of output: 2074
Install mypy in the CI/test environment
The stubtest invocation is failing with:
ModuleNotFoundError: No module named 'mypy'
which indicates mypy isn’t installed in the test runner. To fix this, ensure mypy is listed among your development/test dependencies and is installed before running stubtest:
• In your dev requirements (e.g. requirements-dev.txt or pyproject.toml extras), add:
mypy>=1.0
• In your CI workflow (e.g. .github/workflows/test.yml), install dev deps:
- name: Install dependencies
run: pip install -r requirements-dev.txt• Optionally pin a specific mypy version to ensure consistency across runs.
Once mypy is available, rerun python -m mypy.stubtest … to confirm all stubs pass.
🤖 Prompt for AI Agents
In src/netius/test/base/stubs.py around lines 50 to 71, the stubtest subprocess
call fails because the 'mypy' module is not installed in the test environment.
To fix this, add 'mypy>=1.0' to your development dependencies file (e.g.,
requirements-dev.txt or pyproject.toml extras) and ensure the CI workflow
installs these dev dependencies before running tests. This will make the
'mypy.stubtest' command available and prevent the ModuleNotFoundError during
stubtest execution.
| def _run_stubtest(self, module: str) -> None: | ||
| result = subprocess.run( | ||
| [ | ||
| sys.executable, | ||
| "-m", | ||
| "mypy.stubtest", | ||
| module, | ||
| "--mypy-config-file", | ||
| "/dev/null", | ||
| "--ignore-missing-stub", | ||
| "--allowlist", | ||
| "/dev/null", | ||
| ], | ||
| stdout=subprocess.PIPE, | ||
| stderr=subprocess.STDOUT, | ||
| text=True, | ||
| ) | ||
| self.assertEqual(result.returncode, 0, result.stdout) |
There was a problem hiding this comment.
Fix platform compatibility and add error handling.
The current implementation has several issues that likely contribute to the pipeline failure:
/dev/nullis Unix-specific and will fail on Windows- No error handling if
mypy.stubtestis not installed - Hard-coded paths may not work in CI environments
Consider this more robust implementation:
def _run_stubtest(self, module: str) -> None:
+ import os
+ null_device = os.devnull
+
+ # Check if mypy.stubtest is available
+ try:
+ subprocess.run([sys.executable, "-m", "mypy.stubtest", "--help"],
+ capture_output=True, check=True)
+ except (subprocess.CalledProcessError, FileNotFoundError):
+ self.skipTest("mypy.stubtest not available")
+
result = subprocess.run(
[
sys.executable,
"-m",
"mypy.stubtest",
module,
"--mypy-config-file",
- "/dev/null",
+ null_device,
"--ignore-missing-stub",
"--allowlist",
- "/dev/null",
+ null_device,
],
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT,
text=True,
)
self.assertEqual(result.returncode, 0, result.stdout)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| def _run_stubtest(self, module: str) -> None: | |
| result = subprocess.run( | |
| [ | |
| sys.executable, | |
| "-m", | |
| "mypy.stubtest", | |
| module, | |
| "--mypy-config-file", | |
| "/dev/null", | |
| "--ignore-missing-stub", | |
| "--allowlist", | |
| "/dev/null", | |
| ], | |
| stdout=subprocess.PIPE, | |
| stderr=subprocess.STDOUT, | |
| text=True, | |
| ) | |
| self.assertEqual(result.returncode, 0, result.stdout) | |
| def _run_stubtest(self, module: str) -> None: | |
| import os | |
| null_device = os.devnull | |
| # Check if mypy.stubtest is available | |
| try: | |
| subprocess.run( | |
| [sys.executable, "-m", "mypy.stubtest", "--help"], | |
| capture_output=True, | |
| check=True, | |
| ) | |
| except (subprocess.CalledProcessError, FileNotFoundError): | |
| self.skipTest("mypy.stubtest not available") | |
| result = subprocess.run( | |
| [ | |
| sys.executable, | |
| "-m", | |
| "mypy.stubtest", | |
| module, | |
| "--mypy-config-file", | |
| null_device, | |
| "--ignore-missing-stub", | |
| "--allowlist", | |
| null_device, | |
| ], | |
| stdout=subprocess.PIPE, | |
| stderr=subprocess.STDOUT, | |
| text=True, | |
| ) | |
| self.assertEqual(result.returncode, 0, result.stdout) |
🤖 Prompt for AI Agents
In src/netius/test/base/stubs.py around lines 50 to 67, replace the hard-coded
Unix-specific "/dev/null" paths with a platform-independent approach using
tempfile or appropriate null device handling for Windows. Add error handling to
catch exceptions if "mypy.stubtest" is not installed or subprocess.run fails,
and provide informative error messages. Avoid hard-coded paths by dynamically
determining or mocking necessary files to ensure compatibility and reliability
in CI environments.
Summary
Testing
black .pytest -qhttps://chatgpt.com/codex/tasks/task_e_6845c99064488328bb41065c4cffb391
Summary by CodeRabbit
New Features
Documentation