Skip to content

Commit 1c8da84

Browse files
zpointclaude
andcommitted
Improve English grammar and readability across documentation
Fix grammar issues throughout the repository's markdown files: - Correct spelling errors (e.g., defination → definition, intepreter → interpreter) - Fix capitalization at sentence starts - Correct article usage and verb agreement - Fix run-on sentences with proper punctuation - Standardize technical terms (e.g., posix → POSIX, python → Python) - Fix possessive vs contraction errors (it's → its) Addresses issue #59 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 51a27d8 commit 1c8da84

35 files changed

Lines changed: 715 additions & 722 deletions

File tree

BasicObject/bytearray/bytearray.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ The **ob_alloc** field represents the real allocated size in bytes
4646

4747
## append
4848

49-
after append a charracter 'a', **ob_alloc** becomes 2, **ob_bytes** and **ob_start** all points to same address
49+
After appending a character 'a', **ob_alloc** becomes 2, and **ob_bytes** and **ob_start** both point to the same address
5050

5151
```python3
5252
a.append(ord('a'))
@@ -57,7 +57,7 @@ a.append(ord('a'))
5757

5858
## resize
5959

60-
The size grow pattern is shown in the code
60+
The size growth pattern is shown in the code
6161

6262
```python3
6363
/* Need growing, decide on a strategy */
@@ -72,7 +72,7 @@ The size grow pattern is shown in the code
7272

7373
```
7474

75-
In appending, ob_alloc is 2, and request size is 2, 2 <= 2 * 1.125, so the new allocated size is 2 + (2 >> 3) + 3 ==> 5
75+
When appending, ob_alloc is 2 and the requested size is 2. Since 2 <= 2 * 1.125, the new allocated size is 2 + (2 >> 3) + 3 ==> 5
7676

7777
```python3
7878
a.append(ord('b'))
@@ -99,7 +99,7 @@ b[0:5] = [1,2]
9999

100100
![after_slice](https://github.com/zpoint/CPython-Internals/blob/master/BasicObject/bytearray/after_slice.png)
101101

102-
as long as the slice operation is going to shrink the bytearray, and the **new_size < allocate / 2** is False, the resize operation won't shrink the real malloced size
102+
As long as the slice operation is going to shrink the bytearray and **new_size < allocate / 2** is False, the resize operation won't shrink the actual malloced size
103103

104104
```python3
105105
b[2:6] = [3, 4]
@@ -108,7 +108,7 @@ b[2:6] = [3, 4]
108108

109109
![after2_slice](https://github.com/zpoint/CPython-Internals/blob/master/BasicObject/bytearray/after2_slice.png)
110110

111-
now, in the shrink operation, the **new_size < allocate / 2** is True, the resize operation will be triggered
111+
Now, in the shrink operation, **new_size < allocate / 2** is True, so the resize operation will be triggered
112112

113113
```python3
114114
b[0:3] = [7,8]
@@ -119,7 +119,7 @@ b[0:3] = [7,8]
119119

120120
The growing pattern in slice operation is the same as the append operation
121121

122-
request size is 6, 6 < 6 * 1.125, so new allocated size is 6 + (6 >> 3) + 3 ==> 9
122+
The requested size is 6. Since 6 < 6 * 1.125, the new allocated size is 6 + (6 >> 3) + 3 ==> 9
123123

124124
```python3
125125
b[0:3] = [1,2,3,4]
@@ -130,7 +130,7 @@ b[0:3] = [1,2,3,4]
130130

131131
## ob_exports
132132

133-
what's field **ob_exports** mean ? If you need detail, you can refer to [less-copies-in-python-with-the-buffer-protocol-and-memoryviews](https://eli.thegreenplace.net/2011/11/28/less-copies-in-python-with-the-buffer-protocol-and-memoryviews) and [PEP 3118](https://www.python.org/dev/peps/pep-3118/)
133+
What does the field **ob_exports** mean? If you need details, you can refer to [less-copies-in-python-with-the-buffer-protocol-and-memoryviews](https://eli.thegreenplace.net/2011/11/28/less-copies-in-python-with-the-buffer-protocol-and-memoryviews) and [PEP 3118](https://www.python.org/dev/peps/pep-3118/)
134134

135135
```python3
136136
buf = bytearray(b"abcdefg")
@@ -139,9 +139,9 @@ buf = bytearray(b"abcdefg")
139139

140140
![exports](https://github.com/zpoint/CPython-Internals/blob/master/BasicObject/bytearray/exports.png)
141141

142-
the **bytearray** implements the **buffer protocol**, and **memoryview** is able to access the internal data block via the **buffer protocol**, **mybuf** and **buf** are all sharing the same internal block
142+
The **bytearray** implements the **buffer protocol**, and **memoryview** is able to access the internal data block via the **buffer protocol**. **mybuf** and **buf** both share the same internal block.
143143

144-
field **ob_exports** becomes 1, which indicate how many objects currently sharing the internal block via **buffer protocol**
144+
The field **ob_exports** becomes 1, which indicates how many objects are currently sharing the internal block via the **buffer protocol**
145145

146146
```python3
147147
mybuf = memoryview(buf)
@@ -151,7 +151,7 @@ mybuf[1] = 3
151151

152152
![exports_1](https://github.com/zpoint/CPython-Internals/blob/master/BasicObject/bytearray/exports_1.png)
153153

154-
so does **mybuf2** object(**ob_exports** doesn't change because you need to call the c function defined by **buf** object via the **buffer protocol**, **mybuf2** barely calls the slice function of **mybuf**)
154+
The same applies to the **mybuf2** object (**ob_exports** doesn't change because you need to call the C function defined by the **buf** object via the **buffer protocol**; **mybuf2** only calls the slice function of **mybuf**)
155155

156156
```python3
157157
mybuf2 = mybuf[:4]

BasicObject/bytes/bytes.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ s = b""
3939

4040
## ascii characters
4141

42-
let's initialize a byte object with ascii characters
42+
Let's initialize a bytes object with ASCII characters
4343

4444
```python3
4545
s = b"abcdefg123"
@@ -65,17 +65,17 @@ s = "我是帅哥".encode("utf8")
6565

6666
The field **ob_shash** should store the hash value of the byte object, value **-1** means not computed yet.
6767

68-
The first time the hash value computed, it will be cached in the **ob_shash** field
68+
The first time the hash value is computed, it will be cached in the **ob_shash** field.
6969

70-
the cached hash value can save recalculation and speeds up dictionary lookups
70+
The cached hash value can save recalculation and speed up dictionary lookups
7171

7272
## ob_size
7373

74-
field **ob_size** is inside every **PyVarObject**, the **PyBytesObject** uses this **field** to store size information to keep O(1) time complexity for **len()** operation and tracks the size of non-ascii string(may be null characters inside)
74+
The field **ob_size** is inside every **PyVarObject**. **PyBytesObject** uses this field to store size information to keep O(1) time complexity for the **len()** operation and to track the size of non-ASCII strings (which may contain null characters inside)
7575

7676
## summary
7777

78-
The **PyBytesObject** is a python wrapper of c style null terminate string, with **ob_shash** for caching hash value and **ob_size** for storing the size information of **PyBytesObject**
78+
The **PyBytesObject** is a Python wrapper of C-style null-terminated strings, with **ob_shash** for caching the hash value and **ob_size** for storing size information
7979

8080
The implementation of **PyBytesObject** looks like the **embstr** encoding in redis
8181

BasicObject/class/class.md

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818

1919
# memory layout
2020

21-
the **PyMethodObject** represents the type **method** in c-level
21+
**PyMethodObject** represents the type **method** at the C level
2222

2323
```python3
2424
class C(object):
@@ -35,7 +35,7 @@ class C(object):
3535

3636
# fields
3737

38-
the layout of **c.f1**
38+
The layout of **c.f1**
3939

4040
![example0](https://github.com/zpoint/CPython-Internals/blob/master/BasicObject/class/example0.png)
4141

@@ -51,7 +51,7 @@ as you can see from the layout, field **im_func** stores the [function](https://
5151

5252
## im_self
5353

54-
field **im_self** stores the instance object this method bound to
54+
The field **im_self** stores the instance object this method is bound to
5555

5656
```python3
5757
>>> c
@@ -67,7 +67,7 @@ when you call
6767

6868
```
6969

70-
the **PyMethodObject** delegate the real call to **im_func** with **im_self** as the first argument
70+
**PyMethodObject** delegates the real call to **im_func** with **im_self** as the first argument
7171

7272
```c
7373
static PyObject *
@@ -99,11 +99,11 @@ static int numfree = 0;
9999
100100
```
101101

102-
free_list is a single linked list, it's used for **PyMethodObject** to safe malloc/free overhead
102+
free_list is a singly linked list. It's used for **PyMethodObject** to save malloc/free overhead.
103103

104-
**im_self** field is used to chain the element
104+
The **im_self** field is used to chain the elements.
105105

106-
the **PyMethodObject** will be created when you trying to access the bound-method, not when the instance is created
106+
The **PyMethodObject** will be created when you try to access the bound-method, not when the instance is created
107107

108108
```python3
109109
>>> c1 = C()
@@ -121,7 +121,7 @@ the **PyMethodObject** will be created when you trying to access the bound-metho
121121

122122
```
123123

124-
now, let's see an example of free_list
124+
Now let's see an example of free_list
125125

126126
```python3
127127
>>> c1_f1_1 = c1.f1
@@ -156,7 +156,7 @@ assume the free_list is empty now
156156

157157
# classmethod and staticmethod
158158

159-
let's define an object with **classmethod** and **staticmethod**
159+
Let's define an object with **classmethod** and **staticmethod**
160160

161161
```python3
162162
class C(object):
@@ -193,7 +193,7 @@ the **@classmethod** keeps type of **c1.fc** as **method**
193193

194194
![classmethod](https://github.com/zpoint/CPython-Internals/blob/master/BasicObject/class/classmethod.png)
195195

196-
how **classmethod** work internally?
196+
How does **classmethod** work internally?
197197

198198
**classmethod** is a **type** in python3
199199

@@ -208,7 +208,7 @@ typedef struct {
208208

209209
![classmethod1](https://github.com/zpoint/CPython-Internals/blob/master/BasicObject/class/classmethod1.png)
210210

211-
let's see what's under the hood
211+
Let's see what's under the hood
212212

213213
```python3
214214
fc = classmethod(lambda self : self)
@@ -228,9 +228,9 @@ class C(object):
228228

229229
```
230230

231-
get a different result when access the same object in a different way, why?
231+
We get a different result when accessing the same object in a different way. Why?
232232

233-
when you trying to access the **fc1** in instance cc, the **descriptor protocol** will try several different paths to get the attribute in the following step
233+
When you try to access **fc1** in instance cc, the **descriptor protocol** will try several different paths to get the attribute in the following steps
234234
* call `__getattribute__` of the object C
235235
* `C.__dict__["fc1"]` is a data descriptor?
236236
* yes, return `C.__dict__['fc1'].__get__(instance, Class)`
@@ -246,7 +246,7 @@ for more detail, please refer to this blog [object-attribute-lookup](https://blo
246246

247247
because **classmethod** implements `__get__` and `__set__`, it's a data descriptor, when you try to access attribute **cc.fc1**, you will actually call `fc1.__get__`, and caller will get whatever it returns
248248

249-
we can see the `__get__` function of classmethod object(defined as `cm_descr_get` in C)
249+
We can see the `__get__` function of the classmethod object (defined as `cm_descr_get` in C)
250250

251251
```c
252252
static PyObject *
@@ -268,7 +268,7 @@ cm_descr_get(PyObject *self, PyObject *obj, PyObject *type)
268268
269269
![classmethod_get](https://github.com/zpoint/CPython-Internals/blob/master/BasicObject/class/classmethod_get.png)
270270
271-
when you access fc1 by **cc.fc1**, the **descriptor protocol** will call the function above, which returns whatever in the **cm_callable**, wrapped by **PyMethod_New()** function, which makes the return object a new bounded-PyMethodObject
271+
When you access fc1 via **cc.fc1**, the **descriptor protocol** will call the function above, which returns whatever is in **cm_callable**, wrapped by the **PyMethod_New()** function, which makes the returned object a new bound PyMethodObject
272272
273273
## staticmethod
274274
@@ -291,7 +291,7 @@ typedef struct {
291291

292292
```
293293

294-
this is the layout of **staticmethod** object
294+
This is the layout of the **staticmethod** object
295295

296296
![staticmethod1](https://github.com/zpoint/CPython-Internals/blob/master/BasicObject/class/staticmethod1.png)
297297

@@ -315,7 +315,7 @@ class C(object):
315315

316316
![staticmethod2](https://github.com/zpoint/CPython-Internals/blob/master/BasicObject/class/staticmethod2.png)
317317

318-
we can see the `__get__` function of staticmethod object
318+
We can see the `__get__` function of the staticmethod object
319319

320320
```c
321321
static PyObject *

BasicObject/complex/complex.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,9 @@
1313

1414
# memory layout
1515

16-
the **PyComplexObject** stores two double precision floating point number inside
16+
**PyComplexObject** stores two double-precision floating-point numbers inside.
1717

18-
the handling process and representation are mostly the same as [float](https://github.com/zpoint/CPython-Internals/blob/master/BasicObject/float/float.md) object
18+
The handling process and representation are mostly the same as the [float](https://github.com/zpoint/CPython-Internals/blob/master/BasicObject/float/float.md) object
1919

2020
![layout](https://github.com/zpoint/CPython-Internals/blob/master/BasicObject/complex/layout.png)
2121

@@ -35,7 +35,7 @@ d = complex(0.1, -0.2)
3535

3636
![example1](https://github.com/zpoint/CPython-Internals/blob/master/BasicObject/complex/example1.png)
3737

38-
let's read the add function
38+
Let's read the add function
3939

4040
```c
4141
Py_complex
@@ -62,9 +62,9 @@ complex_add(PyObject *v, PyObject *w)
6262

6363
```
6464
65-
the add operation is quite simple, sum the **real**, sum the **image** part and return the new value
65+
The add operation is quite simple: sum the **real** parts, sum the **imag** parts, and return the new value.
6666
67-
the sub/divide/pow/neg operations are similar
67+
The sub/divide/pow/neg operations are similar
6868
6969
```python3
7070
>>> e = c + d

0 commit comments

Comments
 (0)