Python Object Creation

/**
 * Create a Python integer from a JavaScript number, BigInt, or PyObject
 * @param v - Numeric value to convert
 * @returns PyObject representing a Python int
 */
static int(v: number | bigint | PyObject): PyObject;

/**
 * Create a Python float from a JavaScript number or PyObject
 * @param v - Numeric value to convert
 * @returns PyObject representing a Python float
 */
static float(v: number | PyObject): PyObject;

// Integer creation
const pyInt = PyObject.int(42);
const bigPyInt = PyObject.int(123456789012345678901234567890n);
const fromPyObj = PyObject.int(existingPyObject);

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

console.log(pyInt.toJS()); // 42
console.log(pyFloat.toJS()); // 3.14159

/**
 * Create a Python string from a JavaScript string
 * @param v - String value to convert
 * @returns PyObject representing a Python str
 */
static string(v: string): PyObject;

const pyString = PyObject.string('Hello, Python!');
const emptyString = PyObject.string('');
const unicodeString = PyObject.string('Hello, 世界! 🌍');

console.log(pyString.toString()); // "Hello, Python!"
console.log(pyString.toJS()); // "Hello, Python!"

/**
 * Create a Python dictionary from a JavaScript object
 * @param object - JavaScript object to convert
 * @returns PyObject representing a Python dict
 */
static dict(object: Record<string, any>): PyObject;

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

/**
 * Create a Python tuple from a JavaScript array or PyObject list
 * @param array - Array or list to convert
 * @returns PyObject representing a Python tuple
 */
static tuple(array: any[] | PyObject): PyObject;

// Dictionary creation
const pyDict = PyObject.dict({
  name: 'Alice',
  age: 30,
  active: true,
  scores: [95, 87, 92]
});

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

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

// Access elements
console.log(pyDict.item('name').toJS()); // 'Alice'
console.log(pyList.item(0).toJS()); // 1
console.log(pyTuple.item(-1).toJS()); // 3

/**
 * Create a Python set from a JavaScript array or iterable PyObject
 * @param v - Array or iterable to convert
 * @returns PyObject representing a Python set
 */
static set(v: any[] | PyObject): PyObject;

/**
 * Create a Python frozenset from a JavaScript array or iterable PyObject
 * @param v - Array or iterable to convert
 * @returns PyObject representing a Python frozenset
 */
static frozenSet(v: any[] | PyObject): PyObject;

// Set creation (mutable, unique elements)
const pySet = PyObject.set([1, 2, 3, 2, 1]); // Duplicates removed
const emptySet = PyObject.set([]);

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

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

// Add elements to set
const add = pySet.get('add');
add.call(4);
console.log(pySet.toJS()); // [1, 2, 3, 4]

/**
 * Create a Python slice object for array slicing
 * @param slice - Slice parameters as array [start, stop, step] or object
 * @returns PyObject representing a Python slice
 */
static slice(slice: [PyNumber, PyNumber, PyNumber] | {
  start?: PyNumber;
  stop?: PyNumber;
  step?: PyNumber;
}): PyObject;

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

// Slice creation with object syntax
const slice3 = PyObject.slice({
  start: 0,
  stop: 10,
  step: 2
});

// Use with arrays
const np = proxify(pymport('numpy'));
const array = np.arange(10);
const sliced = array.item(slice1);
console.log(sliced.toJS()); // [1, 2, 3, 4]

/**
 * Create a Python bytes object from a Buffer (immutable, copied)
 * @param buffer - Buffer to convert
 * @returns PyObject representing Python bytes
 */
static bytes(buffer: Buffer): PyObject;

/**
 * Create a Python bytearray object from a Buffer (mutable, copied)
 * @param buffer - Buffer to convert
 * @returns PyObject representing Python bytearray
 */
static bytearray(buffer: Buffer): PyObject;

/**
 * Create a Python memoryview object from a Buffer (references Buffer directly)
 * @param buffer - Buffer to reference
 * @returns PyObject representing Python memoryview
 */
static memoryview(buffer: Buffer): PyObject;

const buffer = Buffer.from('Hello, World!', 'utf8');

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

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

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

// Convert back to Buffer
const backToBuffer = pyBytes.toJS();
console.log(backToBuffer.toString()); // "Hello, World!"

/**
 * Create a Python callable from a JavaScript function
 * @param fn - JavaScript function to wrap
 * @returns PyObject representing a Python callable
 */
static func(fn: (...args: any[]) => any): PyObject;

// Create Python function from JavaScript
const jsFunction = (x, y) => x + y;
const pyFunction = PyObject.func(jsFunction);

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

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

/**
 * Create a PyObject with automatic type detection from JavaScript value
 * - number → int (no decimal) or float (with decimal)
 * - bigint → int
 * - boolean → bool
 * - string → str
 * - null/undefined → None
 * - Array → list
 * - Object → dict
 * - Buffer → bytearray
 * - Function → callable
 * - PyObject → passed through by reference
 * 
 * @param v - JavaScript value to convert
 * @returns PyObject with appropriate Python type
 */
static fromJS(v: any): PyObject;

// Automatic type detection
const pyInt = PyObject.fromJS(42);           // Python int
const pyFloat = PyObject.fromJS(3.14);       // Python float
const pyBool = PyObject.fromJS(true);        // Python bool
const pyStr = PyObject.fromJS('hello');      // Python str
const pyNone = PyObject.fromJS(null);        // Python None
const pyList = PyObject.fromJS([1, 2, 3]);   // Python list
const pyDict = PyObject.fromJS({a: 1});      // Python dict

// Complex nested structures
const complex = PyObject.fromJS({
  numbers: [1, 2, 3.14],
  metadata: {
    active: true,
    name: 'test'
  },
  callback: (x) => x * 2
});

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