0
# Python Object Creation
1

2
Static factory methods for creating Python objects from JavaScript values, supporting all Python built-in types with proper type mapping and memory management.
3

4
## Capabilities
5

6
### Numeric Types
7

8
Create Python numeric objects from JavaScript numbers and BigInts.
9

10
```typescript { .api }
11
/**
12
 * Create a Python integer from a JavaScript number, BigInt, or PyObject
13
 * @param v - Numeric value to convert
14
 * @returns PyObject representing a Python int
15
 */
16
static int(v: number | bigint | PyObject): PyObject;
17

18
/**
19
 * Create a Python float from a JavaScript number or PyObject
20
 * @param v - Numeric value to convert
21
 * @returns PyObject representing a Python float
22
 */
23
static float(v: number | PyObject): PyObject;
24
```
25

26
**Usage Examples:**
27

28
```javascript
29
// Integer creation
30
const pyInt = PyObject.int(42);
31
const bigPyInt = PyObject.int(123456789012345678901234567890n);
32
const fromPyObj = PyObject.int(existingPyObject);
33

34
// Float creation
35
const pyFloat = PyObject.float(3.14159);
36
const floatFromInt = PyObject.float(42); // 42.0
37

38
console.log(pyInt.toJS()); // 42
39
console.log(pyFloat.toJS()); // 3.14159
40
```
41

42
### String Type
43

44
Create Python strings from JavaScript strings.
45

46
```typescript { .api }
47
/**
48
 * Create a Python string from a JavaScript string
49
 * @param v - String value to convert
50
 * @returns PyObject representing a Python str
51
 */
52
static string(v: string): PyObject;
53
```
54

55
**Usage Examples:**
56

57
```javascript
58
const pyString = PyObject.string('Hello, Python!');
59
const emptyString = PyObject.string('');
60
const unicodeString = PyObject.string('Hello, 世界! 🌍');
61

62
console.log(pyString.toString()); // "Hello, Python!"
63
console.log(pyString.toJS()); // "Hello, Python!"
64
```
65

66
### Collection Types
67

68
Create Python collections from JavaScript arrays and objects.
69

70
```typescript { .api }
71
/**
72
 * Create a Python dictionary from a JavaScript object
73
 * @param object - JavaScript object to convert
74
 * @returns PyObject representing a Python dict
75
 */
76
static dict(object: Record<string, any>): PyObject;
77

78
/**
79
 * Create a Python list from a JavaScript array or iterable PyObject
80
 * @param array - Array or iterable to convert
81
 * @returns PyObject representing a Python list
82
 */
83
static list(array: any[] | PyObject): PyObject;
84

85
/**
86
 * Create a Python tuple from a JavaScript array or PyObject list
87
 * @param array - Array or list to convert
88
 * @returns PyObject representing a Python tuple
89
 */
90
static tuple(array: any[] | PyObject): PyObject;
91
```
92

93
**Usage Examples:**
94

95
```javascript
96
// Dictionary creation
97
const pyDict = PyObject.dict({
98
  name: 'Alice',
99
  age: 30,
100
  active: true,
101
  scores: [95, 87, 92]
102
});
103

104
// List creation
105
const pyList = PyObject.list([1, 2, 3, 'hello', true]);
106
const listFromPyObj = PyObject.list(existingPyIterable);
107

108
// Tuple creation (immutable)
109
const pyTuple = PyObject.tuple([1, 2, 3]);
110
const tupleFromList = PyObject.tuple(pyList);
111

112
// Access elements
113
console.log(pyDict.item('name').toJS()); // 'Alice'
114
console.log(pyList.item(0).toJS()); // 1
115
console.log(pyTuple.item(-1).toJS()); // 3
116
```
117

118
### Set Types
119

120
Create Python sets and frozensets from JavaScript arrays.
121

122
```typescript { .api }
123
/**
124
 * Create a Python set from a JavaScript array or iterable PyObject
125
 * @param v - Array or iterable to convert
126
 * @returns PyObject representing a Python set
127
 */
128
static set(v: any[] | PyObject): PyObject;
129

130
/**
131
 * Create a Python frozenset from a JavaScript array or iterable PyObject
132
 * @param v - Array or iterable to convert
133
 * @returns PyObject representing a Python frozenset
134
 */
135
static frozenSet(v: any[] | PyObject): PyObject;
136
```
137

138
**Usage Examples:**
139

140
```javascript
141
// Set creation (mutable, unique elements)
142
const pySet = PyObject.set([1, 2, 3, 2, 1]); // Duplicates removed
143
const emptySet = PyObject.set([]);
144

145
// Frozenset creation (immutable, unique elements)
146
const pyFrozenSet = PyObject.frozenSet([1, 2, 3, 2, 1]);
147

148
// Set operations
149
console.log(pySet.has(2)); // true
150
console.log(pySet.toJS()); // [1, 2, 3] (order may vary)
151

152
// Add elements to set
153
const add = pySet.get('add');
154
add.call(4);
155
console.log(pySet.toJS()); // [1, 2, 3, 4]
156
```
157

158
### Slice Objects
159

160
Create Python slice objects for array slicing operations.
161

162
```typescript { .api }
163
/**
164
 * Create a Python slice object for array slicing
165
 * @param slice - Slice parameters as array [start, stop, step] or object
166
 * @returns PyObject representing a Python slice
167
 */
168
static slice(slice: [PyNumber, PyNumber, PyNumber] | {
169
  start?: PyNumber;
170
  stop?: PyNumber;
171
  step?: PyNumber;
172
}): PyObject;
173
```
174

175
**Usage Examples:**
176

177
```javascript
178
// Slice creation with array syntax
179
const slice1 = PyObject.slice([1, 5, 1]); // start=1, stop=5, step=1
180
const slice2 = PyObject.slice([null, null, 2]); // every 2nd element
181

182
// Slice creation with object syntax
183
const slice3 = PyObject.slice({
184
  start: 0,
185
  stop: 10,
186
  step: 2
187
});
188

189
// Use with arrays
190
const np = proxify(pymport('numpy'));
191
const array = np.arange(10);
192
const sliced = array.item(slice1);
193
console.log(sliced.toJS()); // [1, 2, 3, 4]
194
```
195

196
### Binary Data Types
197

198
Create Python binary data objects from Node.js Buffers.
199

200
```typescript { .api }
201
/**
202
 * Create a Python bytes object from a Buffer (immutable, copied)
203
 * @param buffer - Buffer to convert
204
 * @returns PyObject representing Python bytes
205
 */
206
static bytes(buffer: Buffer): PyObject;
207

208
/**
209
 * Create a Python bytearray object from a Buffer (mutable, copied)
210
 * @param buffer - Buffer to convert
211
 * @returns PyObject representing Python bytearray
212
 */
213
static bytearray(buffer: Buffer): PyObject;
214

215
/**
216
 * Create a Python memoryview object from a Buffer (references Buffer directly)
217
 * @param buffer - Buffer to reference
218
 * @returns PyObject representing Python memoryview
219
 */
220
static memoryview(buffer: Buffer): PyObject;
221
```
222

223
**Usage Examples:**
224

225
```javascript
226
const buffer = Buffer.from('Hello, World!', 'utf8');
227

228
// Bytes (immutable, copied)
229
const pyBytes = PyObject.bytes(buffer);
230
console.log(pyBytes.toJS()); // Buffer equivalent
231

232
// Bytearray (mutable, copied)
233
const pyBytearray = PyObject.bytearray(buffer);
234
pyBytearray.item(0).call(72); // Modify first byte
235

236
// Memoryview (references original Buffer)
237
const pyMemoryview = PyObject.memoryview(buffer);
238
// Changes to buffer will be reflected in memoryview
239

240
// Convert back to Buffer
241
const backToBuffer = pyBytes.toJS();
242
console.log(backToBuffer.toString()); // "Hello, World!"
243
```
244

245
### Function Objects
246

247
Create Python callable objects from JavaScript functions.
248

249
```typescript { .api }
250
/**
251
 * Create a Python callable from a JavaScript function
252
 * @param fn - JavaScript function to wrap
253
 * @returns PyObject representing a Python callable
254
 */
255
static func(fn: (...args: any[]) => any): PyObject;
256
```
257

258
**Usage Examples:**
259

260
```javascript
261
// Create Python function from JavaScript
262
const jsFunction = (x, y) => x + y;
263
const pyFunction = PyObject.func(jsFunction);
264

265
// Use from Python side
266
const result = pyFunction.call(5, 3);
267
console.log(result.toJS()); // 8
268

269
// Pass to Python code that expects a callable
270
const builtins = pymport('builtins');
271
const map = builtins.get('map');
272
const numbers = PyObject.list([1, 2, 3, 4, 5]);
273
const doubled = map.call(PyObject.func(x => x.toJS() * 2), numbers);
274
console.log([...doubled].map(x => x.toJS())); // [2, 4, 6, 8, 10]
275
```
276

277
### Automatic Type Detection
278

279
Automatically create appropriate Python objects from JavaScript values.
280

281
```typescript { .api }
282
/**
283
 * Create a PyObject with automatic type detection from JavaScript value
284
 * - number → int (no decimal) or float (with decimal)
285
 * - bigint → int
286
 * - boolean → bool
287
 * - string → str
288
 * - null/undefined → None
289
 * - Array → list
290
 * - Object → dict
291
 * - Buffer → bytearray
292
 * - Function → callable
293
 * - PyObject → passed through by reference
294
 * 
295
 * @param v - JavaScript value to convert
296
 * @returns PyObject with appropriate Python type
297
 */
298
static fromJS(v: any): PyObject;
299
```
300

301
**Usage Examples:**
302

303
```javascript
304
// Automatic type detection
305
const pyInt = PyObject.fromJS(42);           // Python int
306
const pyFloat = PyObject.fromJS(3.14);       // Python float
307
const pyBool = PyObject.fromJS(true);        // Python bool
308
const pyStr = PyObject.fromJS('hello');      // Python str
309
const pyNone = PyObject.fromJS(null);        // Python None
310
const pyList = PyObject.fromJS([1, 2, 3]);   // Python list
311
const pyDict = PyObject.fromJS({a: 1});      // Python dict
312

313
// Complex nested structures
314
const complex = PyObject.fromJS({
315
  numbers: [1, 2, 3.14],
316
  metadata: {
317
    active: true,
318
    name: 'test'
319
  },
320
  callback: (x) => x * 2
321
});
322

323
// All types detected and converted appropriately
324
console.log(complex.get('numbers').item(2).toJS()); // 3.14
325
console.log(complex.get('metadata').get('active').toJS()); // true
326
```