Michel2/pybricks-api
1
0
Fork 0
mirror of https://github.com/pybricks/pybricks-api.git synced 2026-09-12 09:37:25 +00:00
Code Issues Releases Activity

jedi: improve signature information

Browse Source 
This fixes numerous issues where jedi provided incomplete or poorly
formatted signatures and docstrings.

Issue: https://github.com/pybricks/pybricks-code/issues/932
This commit is contained in:
David Lechner
2022-06-25 23:54:49 -05:00
parent a758eaa1db
commit e95386e23e
12 changed files with 1131 additions and 300 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/pybricks/_common.py
+46 -47
View File
@@ -107,7 +107,7 @@ class DCMotor:
is generated while the motor is still moving."""
@overload
def settings(self, max_voltage: Optional[int] = None) -> None:
def settings(self, max_voltage: Number) -> None:
...
@overload
@@ -140,16 +140,16 @@ class Control:
"""
@overload
def limits(self) -> Tuple[int, int, int]:
def limits(
self,
speed: Optional[Number] = None,
acceleration: Optional[Number] = None,
torque: Optional[Number] = None,
) -> None:
...
@overload
def limits(
self,
speed: Optional[int] = None,
acceleration: Optional[int] = None,
torque: Optional[int] = None,
) -> None:
def limits(self) -> Tuple[int, int, int]:
...
def limits(self, *args):
@@ -173,18 +173,18 @@ class Control:
"""
@overload
def pid(self) -> Tuple[int, int, int, None, int]:
def pid(
self,
kp: Optional[Number] = None,
ki: Optional[Number] = None,
kd: Optional[Number] = None,
reserved: Optional[Number] = None,
integral_rate: Optional[Number] = None,
) -> None:
...
@overload
def pid(
self,
kp: Optional[int] = None,
ki: Optional[int] = None,
kd: Optional[int] = None,
reserved: Optional[int] = None,
integral_rate: Optional[int] = None,
) -> None:
def pid(self) -> Tuple[int, int, int, None, int]:
...
def pid(self, *args):
@@ -210,13 +210,13 @@ class Control:
"""
@overload
def target_tolerances(self) -> Tuple[int, int]:
def target_tolerances(
self, speed: Optional[Number] = None, position: Optional[Number] = None
) -> None:
...
@overload
def target_tolerances(
self, speed: Optional[int] = None, position: Optional[int] = None
) -> None:
def target_tolerances(self) -> Tuple[int, int]:
...
def target_tolerances(self, *args):
@@ -236,13 +236,13 @@ class Control:
"""
@overload
def stall_tolerances(self) -> Tuple[int, int]:
def stall_tolerances(
self, speed: Optional[Number] = None, time: Optional[Number] = None
) -> None:
...
@overload
def stall_tolerances(
self, speed: Optional[int] = None, time: Optional[int] = None
) -> None:
def stall_tolerances(self) -> Tuple[int, int]:
...
def stall_tolerances(self, speed, time):
@@ -356,7 +356,7 @@ class Motor(DCMotor):
"""
def reset_angle(self, angle: Number) -> None:
def reset_angle(self, angle: Optional[Number]) -> None:
"""
reset_angle(angle)
@@ -485,11 +485,11 @@ class Speaker:
"""Plays beeps and sounds using a speaker."""
@overload
def volume(self) -> int:
def volume(self, volume: Number) -> None:
...
@overload
def volume(self, volume: Number) -> None:
def volume(self) -> int:
...
def volume(self, *args):
@@ -570,7 +570,7 @@ class ColorLight:
Turns off the light."""
def blink(self, color: Color, durations: Collection[int]) -> None:
def blink(self, color: Color, durations: Collection[Number]) -> None:
"""blink(color, durations)
Blinks the light at a given color by turning it on and off for given
@@ -599,7 +599,7 @@ class ColorLight:
keeps running. When the animation completes, it repeats.
Arguments:
colors (iter): Sequence of :class:`Color <.parameters.Color>`
colors (list): Sequence of :class:`Color <.parameters.Color>`
values.
interval (Number, ms): Time between color updates.
"""
@@ -617,7 +617,7 @@ class LightArray:
n (int): Number of lights
"""
def on(self, brightness: Union[int, Collection[int]]) -> None:
def on(self, brightness: Union[Number, Collection[Number]]) -> None:
"""on(brightness)
Turns on the lights at the specified brightness.
@@ -688,15 +688,15 @@ class LightMatrix:
interval (Number, ms): Time to display each image in the list.
"""
def pixel(self, row: int, column: int, brightness: Number = 100) -> None:
def pixel(self, row: Number, column: Number, brightness: Number = 100) -> None:
"""pixel(row, column, brightness=100)
Turns on one pixel at the specified brightness.
Arguments:
row (int): Vertical grid index, starting at 0 from the top.
column (int): Horizontal grid index, starting at 0 from the left.
brightness (:ref:`brightness`): Brightness of the pixel.
row (Number): Vertical grid index, starting at 0 from the top.
column (Number): Horizontal grid index, starting at 0 from the left.
brightness (Number :ref:`brightness`): Brightness of the pixel.
"""
def off(self) -> None:
@@ -749,13 +749,13 @@ class Keypad:
def __init__(self, active_buttons):
...
def pressed(self) -> Tuple[Button]:
"""pressed() -> Tuple[Button]
def pressed(self) -> Collection[Button]:
"""pressed() -> Collection[Button]
Checks which buttons are currently pressed.
Returns:
Tuple of pressed buttons.
Set of pressed buttons.
"""
@@ -846,11 +846,11 @@ class Accelerometer(SimpleAccelerometer):
"""Get measurements from an accelerometer."""
@overload
def acceleration(self) -> Matrix:
def acceleration(self, axis: Axis) -> float:
...
@overload
def acceleration(self, axis: Axis) -> float:
def acceleration(self) -> Matrix:
...
def acceleration(self, *args):
@@ -915,11 +915,11 @@ class IMU(Accelerometer):
"""
@overload
def angular_velocity(self) -> Matrix:
def angular_velocity(self, axis: Axis) -> float:
...
@overload
def angular_velocity(self, axis: Axis) -> float:
def angular_velocity(self) -> Matrix:
...
def angular_velocity(self, *args):
@@ -1003,13 +1003,13 @@ class CommonColorSensor:
...
@overload
def detectable_colors(self) -> Tuple[Color]:
def detectable_colors(self) -> Collection[Color]:
...
def detectable_colors(self, *args):
"""
detectable_colors(colors)
detectable_colors() -> Tuple[Color]
detectable_colors() -> Collection[Color]
Configures which colors the ``color()`` method should detect.
@@ -1017,11 +1017,10 @@ class CommonColorSensor:
This way, the full-color measurements are rounded to the nearest
desired color, and other colors are ignored. This improves reliability.
If you give no arguments, the currently chosen colors will be returned
as a tuple.
If you give no arguments, the currently chosen colors will be returned.
Arguments:
colors (tuple): Tuple of :class:`Color <.parameters.Color>`
colors (list or tuple): List of :class:`Color <.parameters.Color>`
objects: the colors that you want to detect. You can pick
standard colors such as ``Color.MAGENTA``, or provide your
own colors like ``Color(h=348, s=96, v=40)`` for even
src/pybricks/geometry.py
+23 -4
View File
@@ -5,7 +5,7 @@
from __future__ import annotations
from typing import Tuple, Collection, overload
from typing import Sequence, Tuple, overload
class Matrix:
@@ -51,7 +51,7 @@ class Matrix:
def __ifloordiv__(self, other) -> Matrix:
...
def __init__(self, rows: Collection[Collection[int]]):
def __init__(self, rows: Sequence[Sequence[float]]):
"""Matrix(rows)
Arguments:
@@ -73,12 +73,31 @@ class Matrix:
@overload
def vector(x: float, y: float) -> Matrix:
...
"""
Convenience function to create a :class:`.Matrix` with the shape (``2``, ``1``).
Arguments:
x (float): x-coordinate of the vector.
y (float): y-coordinate of the vector.
Returns:
A matrix with the shape of a column vector.
"""
@overload
def vector(x: float, y: float, z: float) -> Matrix:
...
"""
Convenience function to create a :class:`.Matrix` with the shape (``3``, ``1``).
Arguments:
x (float): x-coordinate of the vector.
y (float): y-coordinate of the vector.
z (float): z-coordinate of the vector.
Returns:
A matrix with the shape of a column vector.
"""
def vector(*args):
src/pybricks/hubs.py
+7 -3
View File
@@ -4,7 +4,7 @@
"""LEGO® Programmable Hubs."""
from . import _common
from .ev3dev import _speaker
from .geometry import Axis as _Axis
from .geometry import Axis
from .media.ev3dev import Image as _Image
from .parameters import Button as _Button
@@ -63,7 +63,7 @@ class TechnicHub:
system = _common.System()
button = _common.Keypad([_Button.CENTER])
def __init__(self, top_side: _Axis = _Axis.Z, front_side: _Axis = _Axis.X):
def __init__(self, top_side: Axis = Axis.Z, front_side: Axis = Axis.X):
"""TechnicHub(top_side=Axis.Z, front_side=Axis.X)
Initializes the hub. Optionally, specify how the hub is
@@ -100,7 +100,7 @@ class PrimeHub:
imu = _common.IMU()
system = _common.System()
def __init__(self, top_side: _Axis = _Axis.Z, front_side: _Axis = _Axis.X):
def __init__(self, top_side: Axis = Axis.Z, front_side: Axis = Axis.X):
"""PrimeHub(top_side=Axis.Z, front_side=Axis.X)
Initializes the hub. Optionally, specify how the hub is
@@ -118,3 +118,7 @@ class PrimeHub:
class InventorHub(PrimeHub):
"""LEGO® MINDSTORMS Inventor Hub."""
# HACK: hide from jedi
del Axis
src/pybricks/pupdevices.py
+127 -28
View File
@@ -8,25 +8,63 @@ from __future__ import annotations
from typing import TYPE_CHECKING, Collection, Optional, Union, overload, Tuple
from . import _common
from .parameters import (
Button as _Button,
Color as _Color,
Direction as _Direction,
Port as _Port,
)
from .parameters import Button, Color, Direction
if TYPE_CHECKING:
from .parameters import Number as _Number
from .parameters import Number, Port
class DCMotor(_common.DCMotor):
"""LEGO® Powered Up motor without rotation sensors."""
# HACK: jedi can't find inherited __init__ so we have to duplicate docs
def __init__(self, port: Port, positive_direction: Direction = Direction.CLOCKWISE):
"""__init__(port, positive_direction=Direction.CLOCKWISE)
Arguments:
port (Port): Port to which the motor is connected.
positive_direction (Direction): Which direction the motor should
turn when you give a positive duty cycle value.
"""
class Motor(_common.Motor):
"""LEGO® Powered Up motor with rotation sensors."""
def reset_angle(self, angle: Optional[int]) -> None:
# HACK: jedi can't find inherited __init__ so we have to duplicate docs
def __init__(
self,
port: Port,
positive_direction: Direction = Direction.CLOCKWISE,
gears: Optional[Union[Collection[int], Collection[Collection[int]]]] = None,
reset_angle: bool = True,
):
"""__init__(port, positive_direction=Direction.CLOCKWISE, gears=None, reset_angle=True)
Arguments:
port (Port): Port to which the motor is connected.
positive_direction (Direction): Which direction the motor should
turn when you give a positive speed value or
angle.
gears (list):
List of gears linked to the motor.
For example: ``[12, 36]`` represents a gear train with a
12-tooth and a 36-tooth gear. Use a list of lists for multiple
gear trains, such as ``[[12, 36], [20, 16, 40]]``.
When you specify a gear train, all motor commands and settings
are automatically adjusted to account for the resulting gear
ratio. The motor direction remains unchanged by this.
reset_angle(bool):
Choose ``True`` to reset the rotation sensor value to the
absolute marker angle (between -180 and 179).
Choose ``False`` to keep the
current value, so your program knows where it left off last
time.
"""
def reset_angle(self, angle: Optional[Number] = None) -> None:
"""reset_angle(angle=None)
Sets the accumulated rotation angle of the motor to a desired value.
@@ -45,13 +83,13 @@ class Remote:
light = _common.ColorLight()
buttons = _common.Keypad(
(
_Button.LEFT_MINUS,
_Button.RIGHT_MINUS,
_Button.LEFT,
_Button.CENTER,
_Button.RIGHT,
_Button.LEFT_PLUS,
_Button.RIGHT_PLUS,
Button.LEFT_MINUS,
Button.RIGHT_MINUS,
Button.LEFT,
Button.CENTER,
Button.RIGHT,
Button.LEFT_PLUS,
Button.RIGHT_PLUS,
)
)
addresss: Union[str, None]
@@ -94,7 +132,7 @@ class Remote:
class TiltSensor:
"""LEGO® Powered Up Tilt Sensor."""
def __init__(self, port: _Port):
def __init__(self, port: Port):
"""TiltSensor(port)
Arguments:
@@ -116,6 +154,14 @@ class ColorDistanceSensor(_common.CommonColorSensor):
light = _common.ColorLight()
# HACK: jedi can't find inherited __init__ so docs have to be duplicated
def __init__(self, port: Port):
"""__init__(port)
Arguments:
port (Port): Port to which the sensor is connected.
"""
def distance(self) -> int:
"""distance() -> int: %
@@ -135,8 +181,8 @@ class PFMotor(DCMotor):
self,
sensor: ColorDistanceSensor,
channel: int,
color: _Color,
positive_direction: _Direction = _Direction.CLOCKWISE,
color: Color,
positive_direction: Direction = Direction.CLOCKWISE,
):
"""PFMotor(sensor, channel, color, positive_direction=Direction.CLOCKWISE)
@@ -157,15 +203,59 @@ class PFMotor(DCMotor):
class ColorSensor(_common.AmbientColorSensor):
"""LEGO® SPIKE Color Sensor."""
lights = _common.LightArray(3)
class _LightArray(_common.LightArray):
def __init__(self):
super().__init__(3)
def on(self, brightness: Union[Number, Tuple[Number, Number, Number]]) -> None:
"""on(brightness)
Turns on the lights at the specified brightness.
Arguments:
brightness (Number or tuple, %):
A single value will set the brightness of all three lights
to the same value. A tuple of 3 values will set the
brightness of each LED individually.
"""
return super().on(brightness)
lights = _LightArray()
# HACK: jedi can't find inherited __init__ so docs have to be duplicated
def __init__(self, port: Port):
"""__init__(port)
Arguments:
port (Port): Port to which the sensor is connected.
"""
class UltrasonicSensor:
"""LEGO® SPIKE Color Sensor."""
lights = _common.LightArray(3)
class _LightArray(_common.LightArray):
def __init__(self):
super().__init__(4)
def __init__(self, port: _Port):
def on(
self, brightness: Union[Number, Tuple[Number, Number, Number, Number]]
) -> None:
"""on(brightness)
Turns on the lights at the specified brightness.
Arguments:
brightness (Number or tuple, %):
A single value will set the brightness of all four lights
to the same value. A tuple of 4 values will set the
brightness of each LED individually.
"""
return super().on(brightness)
lights = _LightArray()
def __init__(self, port: Port):
"""UltrasonicSensor(port)
Arguments:
@@ -199,7 +289,7 @@ class UltrasonicSensor:
class ForceSensor:
"""LEGO® SPIKE Force Sensor."""
def __init__(self, port: _Port):
def __init__(self, port: Port):
"""ForceSensor(port)
Arguments:
@@ -224,7 +314,7 @@ class ForceSensor:
Movement up to approximately 8.00 mm.
"""
def pressed(self, force: _Number = 3) -> bool:
def pressed(self, force: Number = 3) -> bool:
"""pressed(force=3) -> bool
Checks if the sensor button is pressed.
@@ -255,7 +345,7 @@ class ColorLightMatrix:
LEGO® SPIKE 3x3 Color Light Matrix.
"""
def __init__(self, port: _Port):
def __init__(self, port: Port):
"""ColorLightMatrix(port)
Arguments:
@@ -264,7 +354,7 @@ class ColorLightMatrix:
"""
...
def on(self, color: Union[_Color, Collection[_Color]]) -> None:
def on(self, color: Union[Color, Collection[Color]]) -> None:
"""on(colors)
Turns the lights on.
@@ -288,7 +378,7 @@ class ColorLightMatrix:
class InfraredSensor:
"""LEGO® Powered Up Infrared Sensor."""
def __init__(self, port: _Port):
def __init__(self, port: Port):
"""InfraredSensor(port)
Arguments:
@@ -328,14 +418,14 @@ class InfraredSensor:
class Light:
"""LEGO® Powered Up Light."""
def __init__(self, port: _Port):
def __init__(self, port: Port):
"""Light(port)
Arguments:
port (Port): Port to which the device is connected.
"""
def on(self, brightness: _Number = 100) -> None:
def on(self, brightness: Number = 100) -> None:
"""on(brightness=100)
Turns on the light at the specified brightness.
@@ -349,3 +439,12 @@ class Light:
"""off()
Turns off the light."""
# HACK: exclude from jedi
if TYPE_CHECKING:
del Button
del Color
del Direction
del Number
del Port
src/pybricks/robotics.py
+25 -15
View File
@@ -1,5 +1,5 @@
# SPDX-License-Identifier: MIT
# Copyright (c) 2018-2021 The Pybricks Authors
# Copyright (c) 2018-2022 The Pybricks Authors
"""Robotics module for the Pybricks API."""
@@ -8,10 +8,11 @@ from __future__ import annotations
from typing import Tuple, Optional, overload, TYPE_CHECKING
from . import _common
from .parameters import Stop as _Stop
from .parameters import Stop
if TYPE_CHECKING:
from .parameters import Number as _Number
from ._common import Motor
from .parameters import Number
class DriveBase:
@@ -50,10 +51,10 @@ class DriveBase:
def __init__(
self,
left_motor: _common.Motor,
right_motor: _common.Motor,
wheel_diameter: _Number,
axle_track: _Number,
left_motor: Motor,
right_motor: Motor,
wheel_diameter: Number,
axle_track: Number,
):
"""DriveBase(left_motor, right_motor, wheel_diameter, axle_track)
@@ -67,7 +68,7 @@ class DriveBase:
both wheels touch the ground.
"""
def drive(self, speed: _Number, turn_rate: _Number) -> None:
def drive(self, speed: Number, turn_rate: Number) -> None:
"""drive(speed, turn_rate)
Starts driving at the specified speed and turn rate. Both values are
@@ -118,10 +119,10 @@ class DriveBase:
@overload
def settings(
self,
straight_speed: Optional[_Number],
straight_acceleration: Optional[_Number],
turn_rate: Optional[_Number],
turn_acceleration: Optional[_Number],
straight_speed: Optional[Number] = None,
straight_acceleration: Optional[Number] = None,
turn_rate: Optional[Number] = None,
turn_acceleration: Optional[Number] = None,
) -> None:
...
@@ -147,7 +148,9 @@ class DriveBase:
deceleration of the robot.
"""
def straight(self, distance: _Number, then=_Stop.HOLD, wait=True) -> None:
def straight(
self, distance: Number, then: Stop = Stop.HOLD, wait: bool = True
) -> None:
"""straight(distance, then=Stop.HOLD, wait=True)
Drives straight for a given distance and then stops.
@@ -159,7 +162,7 @@ class DriveBase:
with the rest of the program.
"""
def turn(self, angle: _Number, then=_Stop.HOLD, wait=True) -> None:
def turn(self, angle: Number, then: Stop = Stop.HOLD, wait: bool = True) -> None:
"""turn(angle, then=Stop.HOLD, wait=True)
Turns in place by a given angle and then stops.
@@ -172,7 +175,7 @@ class DriveBase:
"""
def curve(
self, radius: _Number, angle: _Number, then=_Stop.HOLD, wait=True
self, radius: Number, angle: Number, then: Stop = Stop.HOLD, wait: bool = True
) -> None:
"""curve(radius, angle, then=Stop.HOLD, wait=True)
@@ -185,3 +188,10 @@ class DriveBase:
wait (bool): Wait for the maneuver to complete before continuing
with the rest of the program.
"""
# HACK: hide from jedi
if TYPE_CHECKING:
del Motor
del Number
del Stop
src/pybricks/tools.py
+13 -3
View File
@@ -3,10 +3,15 @@
"""Common tools for timing and data logging."""
from typing import Any
from __future__ import annotations
from typing import TYPE_CHECKING, Any
if TYPE_CHECKING:
from .parameters import Number
def wait(time: int) -> None:
def wait(time: Number) -> None:
"""wait(time)
Pauses the user program for a specified amount of time.
@@ -63,7 +68,7 @@ class DataLog:
name: str = "log",
timestamp: bool = True,
extension: str = "csv",
append: bool = False
append: bool = False,
):
"""DataLog(*headers, name='log', timestamp=True, extension='csv', append=False)
@@ -90,3 +95,8 @@ class DataLog:
Arguments:
values (object, object, ...): One or more objects or values.
"""
# HACK: hide from jedi
if TYPE_CHECKING:
del Number