griefith/test
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

PyDoc: use Python's type annotation syntax for doc-strings

Browse Source 
Replace plain-text type information with the type syntax used
for Python's type annotations as it's more concise, especially for
callbacks which often didn't include useful type information.

Note that this change only applies to inline doc-strings,
generated doc-strings from RNA need to be updated separately.

Details:

- Many minor corrections were made when "list" was incorrectly used
  instead of "sequence".
- Some type information wasn't defined in the doc-strings and has been
  added.
- Verbose type info would benefit from support for type aliases.
This commit is contained in:
Campbell Barton
2024-11-03 15:42:19 +11:00
parent 3347aa4017
commit 3bcfb151c1
90 changed files with 722 additions and 676 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
source/blender/python/mathutils/mathutils.cc
View File

@@ -623,21 +623,20 @@ PyObject *BaseMathObject_owner_get(BaseMathObject *self, void * /*closure*/)
}
char BaseMathObject_is_wrapped_doc[] =
"True when this object wraps external data (read-only).\n\n:type: boolean";
"True when this object wraps external data (read-only).\n\n:type: bool";
PyObject *BaseMathObject_is_wrapped_get(BaseMathObject *self, void * /*closure*/)
{
return PyBool_FromLong((self->flag & BASE_MATH_FLAG_IS_WRAP) != 0);
}
char BaseMathObject_is_frozen_doc[] =
"True when this object has been frozen (read-only).\n\n:type: boolean";
"True when this object has been frozen (read-only).\n\n:type: bool";
PyObject *BaseMathObject_is_frozen_get(BaseMathObject *self, void * /*closure*/)
{
return PyBool_FromLong((self->flag & BASE_MATH_FLAG_IS_FROZEN) != 0);
}
char BaseMathObject_is_valid_doc[] =
"True when the owner of this data is valid.\n\n:type: boolean";
char BaseMathObject_is_valid_doc[] = "True when the owner of this data is valid.\n\n:type: bool";
PyObject *BaseMathObject_is_valid_get(BaseMathObject *self, void * /*closure*/)
{
return PyBool_FromLong(BaseMath_CheckCallback(self) == 0);

4
source/blender/python/mathutils/mathutils_Color.cc
View File

@@ -1200,8 +1200,8 @@ PyDoc_STRVAR(
" the OpenColorIO configuration. The notable exception is user interface theming colors, "
" which are in sRGB color space.\n"
"\n"
" :arg rgb: (r, g, b) color values\n"
" :type rgb: 3d vector\n");
" :arg rgb: (red, green, blue) color values where (0, 0, 0) is black & (1, 1, 1) is white.\n"
" :type rgb: Sequence[float]\n");
PyTypeObject color_Type = {
/*ob_base*/ PyVarObject_HEAD_INIT(nullptr, 0)
/*tp_name*/ "Color",

10
source/blender/python/mathutils/mathutils_Euler.cc
View File

@@ -214,7 +214,7 @@ PyDoc_STRVAR(
" (no 720 degree pitches).\n"
"\n"
" :arg axis: single character in ['X, 'Y', 'Z'].\n"
" :type axis: string\n"
" :type axis: str\n"
" :arg angle: angle in radians.\n"
" :type angle: float\n");
static PyObject *Euler_rotate_axis(EulerObject *self, PyObject *args)
@@ -255,7 +255,7 @@ PyDoc_STRVAR(
" Rotates the euler by another mathutils value.\n"
"\n"
" :arg other: rotation component of mathutils value\n"
" :type other: :class:`Euler`, :class:`Quaternion` or :class:`Matrix`\n");
" :type other: :class:`Euler` | :class:`Quaternion` | :class:`Matrix`\n");
static PyObject *Euler_rotate(EulerObject *self, PyObject *value)
{
float self_rmat[3][3], other_rmat[3][3], rmat[3][3];
@@ -707,7 +707,7 @@ PyDoc_STRVAR(
Euler_order_doc,
"Euler rotation order.\n"
"\n"
":type: string in ['XYZ', 'XZY', 'YXZ', 'YZX', 'ZXY', 'ZYX']");
":type: str in ['XYZ', 'XZY', 'YXZ', 'YZX', 'ZXY', 'ZYX']");
static PyObject *Euler_order_get(EulerObject *self, void * /*closure*/)
{
if (BaseMath_ReadCallback(self) == -1) {
@@ -823,8 +823,8 @@ PyDoc_STRVAR(
"\n"
" .. seealso:: `Euler angles <https://en.wikipedia.org/wiki/Euler_angles>`__ on Wikipedia.\n"
"\n"
" :arg angles: Three angles, in radians.\n"
" :type angles: 3d vector\n"
" :arg angles: (X, Y, Z) angles in radians.\n"
" :type angles: Sequence[float]\n"
" :arg order: Optional order of the angles, a permutation of ``XYZ``.\n"
" :type order: str\n");
PyTypeObject euler_Type = {

44
source/blender/python/mathutils/mathutils_Matrix.cc
View File

@@ -692,7 +692,7 @@ PyDoc_STRVAR(
" :type size: int\n"
" :arg axis: a string in ['X', 'Y', 'Z'] or a 3D Vector Object\n"
" (optional when size is 2).\n"
" :type axis: string or :class:`Vector`\n"
" :type axis: str | :class:`Vector`\n"
" :return: A new rotation matrix.\n"
" :rtype: :class:`Matrix`\n");
static PyObject *C_Matrix_Rotation(PyObject *cls, PyObject *args)
@@ -928,7 +928,7 @@ PyDoc_STRVAR(
" :arg axis: Can be any of the following: ['X', 'Y', 'XY', 'XZ', 'YZ'],\n"
" where a single axis is for a 2D matrix.\n"
" Or a vector for an arbitrary axis\n"
" :type axis: string or :class:`Vector`\n"
" :type axis: str | :class:`Vector`\n"
" :arg size: The size of the projection matrix to construct [2, 4].\n"
" :type size: int\n"
" :return: A new projection matrix.\n"
@@ -1049,12 +1049,13 @@ PyDoc_STRVAR(
"\n"
" :arg plane: Can be any of the following: ['X', 'Y', 'XY', 'XZ', 'YZ'],\n"
" where a single axis is for a 2D matrix only.\n"
" :type plane: string\n"
" :type plane: str\n"
" :arg size: The size of the shear matrix to construct [2, 4].\n"
" :type size: int\n"
" :arg factor: The factor of shear to apply. For a 3 or 4 *size* matrix\n"
" pass a pair of floats corresponding with the *plane* axis.\n"
" :type factor: float or float pair\n"
" :arg factor: The factor of shear to apply. "
"For a 2 *size* matrix use a single float. "
"For a 3 or 4 *size* matrix pass a pair of floats corresponding with the *plane* axis.\n"
" :type factor: float | Sequence[float]\n"
" :return: A new shear matrix.\n"
" :rtype: :class:`Matrix`\n");
static PyObject *C_Matrix_Shear(PyObject *cls, PyObject *args)
@@ -1152,13 +1153,14 @@ PyDoc_STRVAR(
" Any of the inputs may be replaced with None if not needed.\n"
"\n"
" :arg location: The translation component.\n"
" :type location: :class:`Vector` or None\n"
" :arg rotation: The rotation component.\n"
" :type rotation: 3x3 :class:`Matrix`, :class:`Quaternion`, :class:`Euler` or None\n"
" :type location: :class:`Vector` | None\n"
" :arg rotation: The rotation component as a "
"3x3 matrix, quaternion, euler or None for no rotation.\n"
" :type rotation: :class:`Matrix` | :class:`Quaternion` | :class:`Euler` | None\n"
" :arg scale: The scale component.\n"
" :type scale: :class:`Vector` or None\n"
" :return: Combined transformation matrix. \n"
" :rtype: 4x4 :class:`Matrix`\n");
" :type scale: :class:`Vector` | None\n"
" :return: Combined transformation as a 4x4 matrix. \n"
" :rtype: :class:`Matrix`\n");
static PyObject *C_Matrix_LocRotScale(PyObject *cls, PyObject *args)
{
PyObject *loc_obj, *rot_obj, *scale_obj;
@@ -1297,7 +1299,7 @@ PyDoc_STRVAR(
"\n"
" :arg order: Optional rotation order argument in\n"
" ['XYZ', 'XZY', 'YXZ', 'YZX', 'ZXY', 'ZYX'].\n"
" :type order: string\n"
" :type order: str\n"
" :arg euler_compat: Optional euler argument the new euler will be made\n"
" compatible with (no axis flipping between them).\n"
" Useful for converting a series of matrices to animation curves.\n"
@@ -1695,9 +1697,9 @@ PyDoc_STRVAR(
"\n"
" :arg fallback: return this when the inverse can't be calculated\n"
" (instead of raising a :exc:`ValueError`).\n"
" :type fallback: any\n"
" :return: the inverted matrix or fallback when given.\n"
" :rtype: :class:`Matrix`\n");
" :type fallback: Any\n"
" :return: The inverted matrix or fallback when given.\n"
" :rtype: :class:`Matrix` | Any\n");
static PyObject *Matrix_inverted(MatrixObject *self, PyObject *args)
{
float mat[MATRIX_MAX_DIM * MATRIX_MAX_DIM];
@@ -1877,7 +1879,7 @@ PyDoc_STRVAR(
" Rotates the matrix by another mathutils value.\n"
"\n"
" :arg other: rotation component of mathutils value\n"
" :type other: :class:`Euler`, :class:`Quaternion` or :class:`Matrix`\n"
" :type other: :class:`Euler` | :class:`Quaternion` | :class:`Matrix`\n"
"\n"
" .. note:: If any of the columns are not unit length this may not have desired results.\n");
static PyObject *Matrix_rotate(MatrixObject *self, PyObject *value)
@@ -1921,8 +1923,8 @@ PyDoc_STRVAR(
"\n"
" Return the translation, rotation, and scale components of this matrix.\n"
"\n"
" :return: tuple of translation, rotation, and scale\n"
" :rtype: (:class:`Vector`, :class:`Quaternion`, :class:`Vector`)");
" :return: Tuple of translation, rotation, and scale.\n"
" :rtype: tuple[:class:`Vector`, :class:`Quaternion`, :class:`Vector`]");
static PyObject *Matrix_decompose(MatrixObject *self)
{
PyObject *ret;
@@ -3107,7 +3109,7 @@ PyDoc_STRVAR(
Matrix_translation_doc,
"The translation component of the matrix.\n"
"\n"
":type: Vector");
":type: :class:`Vector`");
static PyObject *Matrix_translation_get(MatrixObject *self, void * /*closure*/)
{
PyObject *ret;
@@ -3457,7 +3459,7 @@ PyDoc_STRVAR(
" matrices from 2x2 up to 4x4.\n"
"\n"
" :arg rows: Sequence of rows. When omitted, a 4x4 identity matrix is constructed.\n"
" :type rows: 2d number sequence\n");
" :type rows: Sequence[Sequence[float]]\n");
PyTypeObject matrix_Type = {
/*ob_base*/ PyVarObject_HEAD_INIT(nullptr, 0)
/*tp_name*/ "Matrix",

15
source/blender/python/mathutils/mathutils_Quaternion.cc
View File

@@ -173,7 +173,7 @@ PyDoc_STRVAR(
"\n"
" :arg order: Optional rotation order argument in\n"
" ['XYZ', 'XZY', 'YXZ', 'YZX', 'ZXY', 'ZYX'].\n"
" :type order: string\n"
" :type order: str\n"
" :arg euler_compat: Optional euler argument the new euler will be made\n"
" compatible with (no axis flipping between them).\n"
" Useful for converting a series of matrices to animation curves.\n"
@@ -270,8 +270,8 @@ PyDoc_STRVAR(
"\n"
" Return the axis, angle representation of the quaternion.\n"
"\n"
" :return: axis, angle.\n"
" :rtype: (:class:`Vector`, float) pair\n");
" :return: Axis, angle.\n"
" :rtype: tuple[:class:`Vector`, float]\n");
static PyObject *Quaternion_to_axis_angle(QuaternionObject *self)
{
PyObject *ret;
@@ -309,9 +309,10 @@ PyDoc_STRVAR(
" Split the rotation into a swing quaternion with the specified\n"
" axis fixed at zero, and the remaining twist rotation angle.\n"
"\n"
" :arg axis: twist axis as a string in ['X', 'Y', 'Z']\n"
" :return: swing, twist angle.\n"
" :rtype: (:class:`Quaternion`, float) pair\n");
" :arg axis: Twist axis as a string in ['X', 'Y', 'Z'].\n"
" :type axis: str\n"
" :return: Swing, twist angle.\n"
" :rtype: tuple[:class:`Quaternion`, float]\n");
static PyObject *Quaternion_to_swing_twist(QuaternionObject *self, PyObject *axis_arg)
{
PyObject *ret;
@@ -556,7 +557,7 @@ PyDoc_STRVAR(
" Rotates the quaternion by another mathutils value.\n"
"\n"
" :arg other: rotation component of mathutils value\n"
" :type other: :class:`Euler`, :class:`Quaternion` or :class:`Matrix`\n");
" :type other: :class:`Euler` | :class:`Quaternion` | :class:`Matrix`\n");
static PyObject *Quaternion_rotate(QuaternionObject *self, PyObject *value)
{
float self_rmat[3][3], other_rmat[3][3], rmat[3][3];

26
source/blender/python/mathutils/mathutils_Vector.cc
View File

@@ -764,7 +764,7 @@ PyDoc_STRVAR(
" :arg precision: The number to round the value to in [-1, 21].\n"
" :type precision: int\n"
" :return: the values of the vector rounded by *precision*\n"
" :rtype: tuple\n");
" :rtype: tuple[float]\n");
static PyObject *Vector_to_tuple(VectorObject *self, PyObject *args)
{
int ndigits = 0;
@@ -805,9 +805,9 @@ PyDoc_STRVAR(
" Return a quaternion rotation from the vector and the track and up axis.\n"
"\n"
" :arg track: Track axis in ['X', 'Y', 'Z', '-X', '-Y', '-Z'].\n"
" :type track: string\n"
" :type track: str\n"
" :arg up: Up axis in ['X', 'Y', 'Z'].\n"
" :type up: string\n"
" :type up: str\n"
" :return: rotation from the vector and the track and up axis.\n"
" :rtype: :class:`Quaternion`\n");
static PyObject *Vector_to_track_quat(VectorObject *self, PyObject *args)
@@ -1031,8 +1031,8 @@ PyDoc_STRVAR(
"\n"
" :arg other: The other vector to perform the cross product with.\n"
" :type other: :class:`Vector`\n"
" :return: The cross product.\n"
" :rtype: :class:`Vector` or float when 2D vectors are used\n"
" :return: The cross product as a vector or a float when 2D vectors are used.\n"
" :rtype: :class:`Vector` | float\n"
"\n"
" .. note:: both vectors must be 2D or 3D\n");
static PyObject *Vector_cross(VectorObject *self, PyObject *value)
@@ -1121,9 +1121,9 @@ PyDoc_STRVAR(
" :type other: :class:`Vector`\n"
" :arg fallback: return this when the angle can't be calculated (zero length vector),\n"
" (instead of raising a :exc:`ValueError`).\n"
" :type fallback: any\n"
" :type fallback: Any\n"
" :return: angle in radians or fallback when given\n"
" :rtype: float\n");
" :rtype: float | Any\n");
static PyObject *Vector_angle(VectorObject *self, PyObject *args)
{
const int vec_num = std::min(self->vec_num, 3); /* 4D angle makes no sense */
@@ -1194,9 +1194,9 @@ PyDoc_STRVAR(
" :type other: :class:`Vector`\n"
" :arg fallback: return this when the angle can't be calculated (zero length vector),\n"
" (instead of raising a :exc:`ValueError`).\n"
" :type fallback: any\n"
" :type fallback: Any\n"
" :return: angle in radians or fallback when given\n"
" :rtype: float\n");
" :rtype: float | Any\n");
static PyObject *Vector_angle_signed(VectorObject *self, PyObject *args)
{
float tvec[2];
@@ -1400,7 +1400,7 @@ PyDoc_STRVAR(
" :arg fallback: return this when the vector can't be calculated (zero length "
"vector or direct opposites),\n"
" (instead of raising a :exc:`ValueError`).\n"
" :type fallback: any\n"
" :type fallback: Any\n"
" :return: The interpolated vector.\n"
" :rtype: :class:`Vector`\n");
static PyObject *Vector_slerp(VectorObject *self, PyObject *args)
@@ -1491,7 +1491,7 @@ PyDoc_STRVAR(
" .. note:: 2D vectors are a special case that can only be rotated by a 2x2 matrix.\n"
"\n"
" :arg other: rotation component of mathutils value\n"
" :type other: :class:`Euler`, :class:`Quaternion` or :class:`Matrix`\n");
" :type other: :class:`Euler` | :class:`Quaternion` | :class:`Matrix`\n");
static PyObject *Vector_rotate(VectorObject *self, PyObject *value)
{
if (BaseMath_ReadCallback_ForWrite(self) == -1) {
@@ -3405,8 +3405,8 @@ PyDoc_STRVAR(
"\n"
" This object gives access to Vectors in Blender.\n"
"\n"
" :arg seq: Components of the vector, must be a sequence of at least two\n"
" :type seq: sequence of floats\n");
" :arg seq: Components of the vector, must be a sequence of at least two.\n"
" :type seq: Sequence[float]\n");
PyTypeObject vector_Type = {
/*ob_base*/ PyVarObject_HEAD_INIT(nullptr, 0)
/*tp_name*/ "Vector",

16
source/blender/python/mathutils/mathutils_bvhtree.cc
View File

@@ -58,15 +58,13 @@
" :type distance: float\n"
#define PYBVH_FIND_GENERIC_RETURN_DOC \
" :return: Returns a tuple\n" \
" (:class:`Vector` location, :class:`Vector` normal, int index, float distance),\n" \
" :return: Returns a tuple: (position, normal, index, distance),\n" \
" Values will all be None if no hit is found.\n" \
" :rtype: :class:`tuple`\n"
" :rtype: tuple[:class:`Vector` | None, :class:`Vector` | None, int | None, float | None]\n"
#define PYBVH_FIND_GENERIC_RETURN_LIST_DOC \
" :return: Returns a list of tuples\n" \
" (:class:`Vector` location, :class:`Vector` normal, int index, float distance),\n" \
" :rtype: :class:`list`\n"
" :return: Returns a list of tuples (position, normal, index, distance)\n" \
" :rtype: list[tuple[:class:`Vector`, :class:`Vector`, int, float]]\n"
#define PYBVH_FROM_GENERIC_EPSILON_DOC \
" :arg epsilon: Increase the threshold for detecting overlap and raycast hits.\n" \
@@ -559,7 +557,7 @@ PyDoc_STRVAR(
" :type other_tree: :class:`BVHTree`\n"
" :return: Returns a list of unique index pairs,"
" the first index referencing this tree, the second referencing the **other_tree**.\n"
" :rtype: :class:`list`\n");
" :rtype: list[tuple[int, int]]\n");
static PyObject *py_bvhtree_overlap(PyBVHTree *self, PyBVHTree *other)
{
PyBVHTree_OverlapData data;
@@ -642,9 +640,9 @@ PyDoc_STRVAR(
" BVH tree constructed geometry passed in as arguments.\n"
"\n"
" :arg vertices: float triplets each representing ``(x, y, z)``\n"
" :type vertices: float triplet sequence\n"
" :type vertices: Sequence[Sequence[float]]\n"
" :arg polygons: Sequence of polygons, each containing indices to the vertices argument.\n"
" :type polygons: Sequence of sequences containing ints\n"
" :type polygons: Sequence[Sequence[int]]\n"
" :arg all_triangles: Use when all **polygons** are triangles for more efficient "
"conversion.\n"
" :type all_triangles: bool\n" PYBVH_FROM_GENERIC_EPSILON_DOC);

96
source/blender/python/mathutils/mathutils_geometry.cc
View File

@@ -57,9 +57,9 @@ PyDoc_STRVAR(
" :type orig: :class:`mathutils.Vector`\n"
" :arg clip: When False, don't restrict the intersection to the area of the "
"triangle, use the infinite plane defined by the triangle.\n"
" :type clip: boolean\n"
" :type clip: bool\n"
" :return: The point of intersection or None if no intersection is found\n"
" :rtype: :class:`mathutils.Vector` or None\n");
" :rtype: :class:`mathutils.Vector` | None\n");
static PyObject *M_Geometry_intersect_ray_tri(PyObject * /*self*/, PyObject *args)
{
const char *error_prefix = "intersect_ray_tri";
@@ -165,7 +165,7 @@ PyDoc_STRVAR(
" :arg v4: Second point of the second line\n"
" :type v4: :class:`mathutils.Vector`\n"
" :return: The intersection on each line or None when the lines are co-linear.\n"
" :rtype: tuple of :class:`mathutils.Vector`'s\n");
" :rtype: tuple[:class:`mathutils.Vector`, :class:`mathutils.Vector`] | None\n");
static PyObject *M_Geometry_intersect_line_line(PyObject * /*self*/, PyObject *args)
{
const char *error_prefix = "intersect_line_line";
@@ -244,7 +244,8 @@ PyDoc_STRVAR(
" :arg radius_b: Radius of the second circle\n"
" :type radius_b: float\n"
" :return: 2 points on between intersecting circles or None when there is no intersection.\n"
" :rtype: tuple of :class:`mathutils.Vector`'s or None when there is no intersection\n");
" :rtype: tuple[:class:`mathutils.Vector`, :class:`mathutils.Vector`] | tuple[None, "
"None]\n");
static PyObject *M_Geometry_intersect_sphere_sphere_2d(PyObject * /*self*/, PyObject *args)
{
const char *error_prefix = "intersect_sphere_sphere_2d";
@@ -350,8 +351,8 @@ PyDoc_STRVAR(
"\n"
" Returns the normal of a 3D polygon.\n"
"\n"
" :arg vectors: Vectors to calculate normals with\n"
" :type vectors: sequence of 3 or more 3d vector\n"
" :arg vectors: 3 or more vectors to calculate normals.\n"
" :type vectors: Sequence[Sequence[float]]\n"
" :rtype: :class:`mathutils.Vector`\n");
static PyObject *M_Geometry_normal(PyObject * /*self*/, PyObject *args)
{
@@ -476,7 +477,7 @@ PyDoc_STRVAR(
" :arg lineB_p2: Second point of the second line\n"
" :type lineB_p2: :class:`mathutils.Vector`\n"
" :return: The point of intersection or None when not found\n"
" :rtype: :class:`mathutils.Vector` or None\n");
" :rtype: :class:`mathutils.Vector` | None\n");
static PyObject *M_Geometry_intersect_line_line_2d(PyObject * /*self*/, PyObject *args)
{
const char *error_prefix = "intersect_line_line_2d";
@@ -519,7 +520,7 @@ PyDoc_STRVAR(
" :arg plane_no: The direction the plane is facing\n"
" :type plane_no: :class:`mathutils.Vector`\n"
" :return: The point of intersection or None when not found\n"
" :rtype: :class:`mathutils.Vector` or None\n");
" :rtype: :class:`mathutils.Vector` | None\n");
static PyObject *M_Geometry_intersect_line_plane(PyObject * /*self*/, PyObject *args)
{
const char *error_prefix = "intersect_line_plane";
@@ -572,9 +573,10 @@ PyDoc_STRVAR(
" :type plane_b_co: :class:`mathutils.Vector`\n"
" :arg plane_b_no: Normal of the second plane\n"
" :type plane_b_no: :class:`mathutils.Vector`\n"
" :return: The line of the intersection represented as a point and a vector\n"
" :rtype: tuple pair of :class:`mathutils.Vector` or None if the intersection can't be "
"calculated\n");
" :return: The line of the intersection represented as a point and a vector or None if the "
"intersection can't be calculated\n"
" :rtype: tuple[:class:`mathutils.Vector`, :class:`mathutils.Vector`] | tuple[None, "
"None]\n");
static PyObject *M_Geometry_intersect_plane_plane(PyObject * /*self*/, PyObject *args)
{
const char *error_prefix = "intersect_plane_plane";
@@ -645,7 +647,7 @@ PyDoc_STRVAR(
" :type sphere_radius: float\n"
" :return: The intersection points as a pair of vectors or None when there is no "
"intersection\n"
" :rtype: A tuple pair containing :class:`mathutils.Vector` or None\n");
" :rtype: tuple[:class:`mathutils.Vector` | None, :class:`mathutils.Vector` | None]\n");
static PyObject *M_Geometry_intersect_line_sphere(PyObject * /*self*/, PyObject *args)
{
const char *error_prefix = "intersect_line_sphere";
@@ -736,7 +738,7 @@ PyDoc_STRVAR(
" :type sphere_radius: float\n"
" :return: The intersection points as a pair of vectors or None when there is no "
"intersection\n"
" :rtype: A tuple pair containing :class:`mathutils.Vector` or None\n");
" :rtype: tuple[:class:`mathutils.Vector` | None, :class:`mathutils.Vector` | None]\n");
static PyObject *M_Geometry_intersect_line_sphere_2d(PyObject * /*self*/, PyObject *args)
{
const char *error_prefix = "intersect_line_sphere_2d";
@@ -822,7 +824,7 @@ PyDoc_STRVAR(
" :type line_p1: :class:`mathutils.Vector`\n"
" :arg line_p1: Second point of the line\n"
" :type line_p1: :class:`mathutils.Vector`\n"
" :rtype: (:class:`mathutils.Vector`, float)\n");
" :rtype: tuple[:class:`mathutils.Vector`, float]\n");
static PyObject *M_Geometry_intersect_point_line(PyObject * /*self*/, PyObject *args)
{
const char *error_prefix = "intersect_point_line";
@@ -873,7 +875,7 @@ PyDoc_STRVAR(
" :arg tri_p3: Third point of the triangle\n"
" :type tri_p3: :class:`mathutils.Vector`\n"
" :return: Point on the triangles plane or None if its outside the triangle\n"
" :rtype: :class:`mathutils.Vector` or None\n");
" :rtype: :class:`mathutils.Vector` | None\n");
static PyObject *M_Geometry_intersect_point_tri(PyObject * /*self*/, PyObject *args)
{
const char *error_prefix = "intersect_point_tri";
@@ -1096,7 +1098,7 @@ PyDoc_STRVAR(
" :arg tri_b3: target triangle vertex.\n"
" :type tri_b3: :class:`mathutils.Vector`\n"
" :return: The transformed point\n"
" :rtype: :class:`mathutils.Vector`'s\n");
" :rtype: :class:`mathutils.Vector`\n");
static PyObject *M_Geometry_barycentric_transform(PyObject * /*self*/, PyObject *args)
{
const char *error_prefix = "barycentric_transform";
@@ -1154,14 +1156,14 @@ PyDoc_STRVAR(
"the planes used.\n"
"\n"
" :arg planes: List of planes (4D vectors).\n"
" :type planes: list of :class:`mathutils.Vector`\n"
" :type planes: list[:class:`mathutils.Vector`]\n"
" :arg epsilon_coplanar: Epsilon value for interpreting plane pairs as co-plannar.\n"
" :type epsilon_coplanar: float\n"
" :arg epsilon_isect: Epsilon value for intersection.\n"
" :type epsilon_isect: float\n"
" :return: two lists, once containing the vertices inside the planes, another "
"containing the plane indices used\n"
" :rtype: pair of lists\n");
" :return: Two lists, once containing the 3D coordinates inside the planes, "
"another containing the plane indices used.\n"
" :rtype: tuple[list[:class:`mathutils.Vector`], list[int]]\n");
static PyObject *M_Geometry_points_in_planes(PyObject * /*self*/, PyObject *args)
{
PyObject *py_planes;
@@ -1231,8 +1233,8 @@ PyDoc_STRVAR(
" :type knot2: :class:`mathutils.Vector`\n"
" :arg resolution: Number of points to return.\n"
" :type resolution: int\n"
" :return: The interpolated points\n"
" :rtype: list of :class:`mathutils.Vector`'s\n");
" :return: The interpolated points.\n"
" :rtype: list[:class:`mathutils.Vector`]\n");
static PyObject *M_Geometry_interpolate_bezier(PyObject * /*self*/, PyObject *args)
{
const char *error_prefix = "interpolate_bezier";
@@ -1281,14 +1283,16 @@ static PyObject *M_Geometry_interpolate_bezier(PyObject * /*self*/, PyObject *ar
PyDoc_STRVAR(
/* Wrap. */
M_Geometry_tessellate_polygon_doc,
".. function:: tessellate_polygon(veclist_list)\n"
".. function:: tessellate_polygon(polylines)\n"
"\n"
" Takes a list of polylines (each point a pair or triplet of numbers) and returns "
"the point indices for a polyline filled with triangles. Does not handle degenerate "
"geometry (such as zero-length lines due to consecutive identical points).\n"
"\n"
" :arg veclist_list: list of polylines\n"
" :rtype: list\n");
" :arg polylines: Polygons where each polygon is a sequence of 2D or 3D points.\n"
" :type polylines: Sequence[Sequence[Sequence[float]]]"
" :return: A list of triangles.\n"
" :rtype: list[tuple[int, int, int]]\n");
/* PolyFill function, uses Blenders scan-fill to fill multiple poly lines. */
static PyObject *M_Geometry_tessellate_polygon(PyObject * /*self*/, PyObject *polyLineSeq)
{
@@ -1462,11 +1466,12 @@ PyDoc_STRVAR(
"\n"
" Returns a tuple with the width and height of the packed bounding box.\n"
"\n"
" :arg boxes: list of boxes, each box is a list where the first 4 items are [x, y, "
"width, height, ...] other items are ignored.\n"
" :type boxes: list\n"
" :return: the width and height of the packed bounding box\n"
" :rtype: tuple, pair of floats\n");
" :arg boxes: list of boxes, each box is a list where the first 4 items are "
"[X, Y, width, height, ...] other items are ignored. "
"The X & Y values in this list are modified to set the packed positions.\n"
" :type boxes: list[list[float, float, float, float, ...]]\n"
" :return: The width and height of the packed bounding box.\n"
" :rtype: tuple[float, float]\n");
static PyObject *M_Geometry_box_pack_2d(PyObject * /*self*/, PyObject *boxlist)
{
float tot_width = 0.0f, tot_height = 0.0f;
@@ -1506,8 +1511,8 @@ PyDoc_STRVAR(
"\n"
" Returns an angle that best fits the points to an axis aligned rectangle\n"
"\n"
" :arg points: list of 2d points.\n"
" :type points: list\n"
" :arg points: Sequence of 2D points.\n"
" :type points: Sequence[Sequence[float]]\n"
" :return: angle\n"
" :rtype: float\n");
static PyObject *M_Geometry_box_fit_2d(PyObject * /*self*/, PyObject *pointlist)
@@ -1539,10 +1544,10 @@ PyDoc_STRVAR(
"\n"
" Returns a list of indices into the list given\n"
"\n"
" :arg points: list of 2d points.\n"
" :type points: list\n"
" :arg points: Sequence of 2D points.\n"
" :type points: Sequence[Sequence[float]]\n"
" :return: a list of indices\n"
" :rtype: list of ints\n");
" :rtype: list[int]\n");
static PyObject *M_Geometry_convex_hull_2d(PyObject * /*self*/, PyObject *pointlist)
{
float(*points)[2];
@@ -1621,11 +1626,11 @@ PyDoc_STRVAR(
" of the orig arrays, which may save some time.\n"
"\n"
" :arg vert_coords: Vertex coordinates (2d)\n"
" :type vert_coords: list of :class:`mathutils.Vector`\n"
" :arg edges: Edges, as pairs of indices in `vert_coords`\n"
" :type edges: list of (int, int)\n"
" :type vert_coords: Sequence[:class:`mathutils.Vector`]\n"
" :arg edges: Edges, as pairs of indices in ``vert_coords``\n"
" :type edges: Sequence[Sequence[int, int]]\n"
" :arg faces: Faces, each sublist is a face, as indices in `vert_coords` (CCW oriented)\n"
" :type faces: list of list of int\n"
" :type faces: Sequence[Sequence[int]]\n"
" :arg output_type: What output looks like. 0 => triangles with convex hull. "
"1 => triangles inside constraints. "
"2 => the input constraints, intersected. "
@@ -1638,12 +1643,13 @@ PyDoc_STRVAR(
" :arg need_ids: are the orig output arrays needed?\n"
" :type need_args: bool\n"
" :return: Output tuple, (vert_coords, edges, faces, orig_verts, orig_edges, orig_faces)\n"
" :rtype: (list of `mathutils.Vector`, "
"list of (int, int), "
"list of list of int, "
"list of list of int, "
"list of list of int, "
"list of list of int)\n"
" :rtype: tuple["
"list[:class:`mathutils.Vector`], "
"list[tuple[int, int]], "
"list[list[int]], "
"list[list[int]], "
"list[list[int]], "
"list[list[int]]]\n"
"\n");
static PyObject *M_Geometry_delaunay_2d_cdt(PyObject * /*self*/, PyObject *args)
{

9
source/blender/python/mathutils/mathutils_interpolate.cc
View File

@@ -35,9 +35,12 @@ PyDoc_STRVAR(
"\n"
" Calculate barycentric weights for a point on a polygon.\n"
"\n"
" :arg veclist: list of vectors\n"
" :arg pt: point"
" :rtype: list of per-vector weights\n");
" :arg veclist: Sequence of 3D positions.\n"
" :type veclist: Sequence[Sequence[float]]\n"
" :arg pt: 2D or 3D position."
" :type pt: Sequence[float]"
" :return: list of per-vector weights.\n"
" :rtype: list[float]\n");
static PyObject *M_Interpolate_poly_3d_calc(PyObject * /*self*/, PyObject *args)
{
float fp[3];

28
source/blender/python/mathutils/mathutils_kdtree.cc
View File

@@ -115,7 +115,7 @@ PyDoc_STRVAR(
" Insert a point into the KDTree.\n"
"\n"
" :arg co: Point 3d position.\n"
" :type co: float triplet\n"
" :type co: Sequence[float]\n"
" :arg index: The index of the point.\n"
" :type index: int\n");
static PyObject *py_kdtree_insert(PyKDTree *self, PyObject *args, PyObject *kwargs)
@@ -202,13 +202,13 @@ PyDoc_STRVAR(
"\n"
" Find nearest point to ``co``.\n"
"\n"
" :arg co: 3d coordinates.\n"
" :type co: float triplet\n"
" :arg co: 3D coordinates.\n"
" :type co: Sequence[float]\n"
" :arg filter: function which takes an index and returns True for indices to "
"include in the search.\n"
" :type filter: callable\n"
" :return: Returns (:class:`Vector`, index, distance).\n"
" :rtype: :class:`tuple`\n");
" :type filter: Callable[[int], bool]\n"
" :return: Returns (position, index, distance).\n"
" :rtype: tuple[:class:`Vector`, int, float]\n");
static PyObject *py_kdtree_find(PyKDTree *self, PyObject *args, PyObject *kwargs)
{
PyObject *py_co, *py_filter = nullptr;
@@ -259,12 +259,12 @@ PyDoc_STRVAR(
"\n"
" Find nearest ``n`` points to ``co``.\n"
"\n"
" :arg co: 3d coordinates.\n"
" :type co: float triplet\n"
" :arg co: 3D coordinates.\n"
" :type co: Sequence[float]\n"
" :arg n: Number of points to find.\n"
" :type n: int\n"
" :return: Returns a list of tuples (:class:`Vector`, index, distance).\n"
" :rtype: :class:`list`\n");
" :return: Returns a list of tuples (position, index, distance).\n"
" :rtype: list[tuple[:class:`Vector`, int, float]]\n");
static PyObject *py_kdtree_find_n(PyKDTree *self, PyObject *args, PyObject *kwargs)
{
PyObject *py_list;
@@ -315,12 +315,12 @@ PyDoc_STRVAR(
"\n"
" Find all points within ``radius`` of ``co``.\n"
"\n"
" :arg co: 3d coordinates.\n"
" :type co: float triplet\n"
" :arg co: 3D coordinates.\n"
" :type co: Sequence[float]\n"
" :arg radius: Distance to search for points.\n"
" :type radius: float\n"
" :return: Returns a list of tuples (:class:`Vector`, index, distance).\n"
" :rtype: :class:`list`\n");
" :return: Returns a list of tuples (position, index, distance).\n"
" :rtype: list[tuple[:class:`Vector`, int, float]]\n");
static PyObject *py_kdtree_find_range(PyKDTree *self, PyObject *args, PyObject *kwargs)
{
PyObject *py_list;

14
source/blender/python/mathutils/mathutils_noise.cc
View File

@@ -150,13 +150,13 @@ static float frand()
"'VORONOI_F1', 'VORONOI_F2', " \
"'VORONOI_F3', 'VORONOI_F4', 'VORONOI_F2F1', 'VORONOI_CRACKLE', " \
"'CELLNOISE'].\n" \
" :type noise_basis: string\n"
" :type noise_basis: str\n"
#define BPY_NOISE_METRIC_ENUM_DOC \
" :arg distance_metric: Enumerator in ['DISTANCE', 'DISTANCE_SQUARED', 'MANHATTAN', " \
"'CHEBYCHEV', " \
"'MINKOVSKY', 'MINKOVSKY_HALF', 'MINKOVSKY_FOUR'].\n" \
" :type distance_metric: string\n"
" :type distance_metric: str\n"
/* Noise basis enum */
#define DEFAULT_NOISE_TYPE TEX_STDPERLIN
@@ -487,7 +487,7 @@ PyDoc_STRVAR(
" :type octaves: int\n"
" :arg hard: Specifies whether returned turbulence is hard (sharp transitions) or "
"soft (smooth transitions).\n"
" :type hard: boolean\n" BPY_NOISE_BASIS_ENUM_DOC
" :type hard: bool\n" BPY_NOISE_BASIS_ENUM_DOC
" :arg amplitude_scale: The amplitude scaling factor.\n"
" :type amplitude_scale: float\n"
" :arg frequency_scale: The frequency scaling factor\n"
@@ -548,7 +548,7 @@ PyDoc_STRVAR(
" :type octaves: int\n"
" :arg hard: Specifies whether returned turbulence is hard (sharp transitions) or "
"soft (smooth transitions).\n"
" :type hard: boolean\n" BPY_NOISE_BASIS_ENUM_DOC
" :type hard: bool\n" BPY_NOISE_BASIS_ENUM_DOC
" :arg amplitude_scale: The amplitude scaling factor.\n"
" :type amplitude_scale: float\n"
" :arg frequency_scale: The frequency scaling factor\n"
@@ -722,12 +722,12 @@ PyDoc_STRVAR(
"'VORONOI_F1', 'VORONOI_F2', "
"'VORONOI_F3', 'VORONOI_F4', 'VORONOI_F2F1', 'VORONOI_CRACKLE', "
"'CELLNOISE'].\n"
" :type noise_type1: string\n"
" :type noise_type1: str\n"
" :arg noise_type2: Enumerator in ['BLENDER', 'PERLIN_ORIGINAL', 'PERLIN_NEW', "
"'VORONOI_F1', 'VORONOI_F2', "
"'VORONOI_F3', 'VORONOI_F4', 'VORONOI_F2F1', 'VORONOI_CRACKLE', "
"'CELLNOISE'].\n"
" :type noise_type2: string\n"
" :type noise_type2: str\n"
" :return: The variable lacunarity noise value.\n"
" :rtype: float\n");
static PyObject *M_Noise_variable_lacunarity(PyObject * /*self*/, PyObject *args, PyObject *kw)
@@ -980,7 +980,7 @@ PyDoc_STRVAR(
" :arg exponent: The exponent for Minkowski distance metric.\n"
" :type exponent: float\n"
" :return: A list of distances to the four closest features and their locations.\n"
" :rtype: list of four floats, list of four :class:`mathutils.Vector` types\n");
" :rtype: list[list[float], list[:class:`mathutils.Vector`]]\n");
static PyObject *M_Noise_voronoi(PyObject * /*self*/, PyObject *args, PyObject *kw)
{
static const char *kwlist[] = {"", "distance_metric", "exponent", nullptr};