Python Object Operations

/**
 * Get reference count of a Python object
 * @param ob - Python object
 * @return Current reference count
 */
public static native long Py_REFCNT(PyObject ob);

/**
 * Set reference count of a Python object
 * @param ob - Python object
 * @param refcnt - New reference count
 */
public static native void Py_SET_REFCNT(PyObject ob, long refcnt);

/**
 * Set reference count (internal version)
 * @param ob - Python object  
 * @param refcnt - New reference count
 */
public static native void _Py_SetRefcnt(PyObject ob, long refcnt);

/**
 * Check if object is immortal (never deallocated)
 * @param op - Python object
 * @return Non-zero if object is immortal
 */
public static native int _Py_IsImmortal(PyObject op);

/**
 * Test object identity (equivalent to Python 'is' operator)
 * @param x - First object
 * @param y - Second object
 * @return Non-zero if objects are identical
 */
public static native int Py_Is(PyObject x, PyObject y);

/**
 * Get type of a Python object
 * @param ob - Python object
 * @return Type object
 */
public static native PyTypeObject Py_TYPE(PyObject ob);

/**
 * Check if object is of specific type
 * @param ob - Python object
 * @param type - Type to check against
 * @return Non-zero if object is of specified type
 */
public static native int Py_IS_TYPE(PyObject ob, PyTypeObject type);

/**
 * Set type of a Python object
 * @param ob - Python object
 * @param type - New type
 */
public static native void Py_SET_TYPE(PyObject ob, PyTypeObject type);

/**
 * Get size of variable-length object
 * @param ob - Python object
 * @return Size of object
 */
public static native long Py_SIZE(PyObject ob);

/**
 * Set size of variable-length object
 * @param ob - Python variable object
 * @param size - New size
 */
public static native void Py_SET_SIZE(PyVarObject ob, long size);

/**
 * Compute hash value of an object
 * @param obj - Python object
 * @return Hash value, or -1 on error
 */
public static native long PyObject_Hash(PyObject obj);

/**
 * Enter recursive representation (for avoiding infinite recursion in repr)
 * @param obj - Python object
 * @return 0 on success, 1 if already entered, -1 on error
 */
public static native int Py_ReprEnter(PyObject obj);

/**
 * Leave recursive representation
 * @param obj - Python object
 */
public static native void Py_ReprLeave(PyObject obj);

import static org.bytedeco.cpython.global.python.*;

// Create an object and check its properties
PyObject obj = PyUnicode_FromString("Hello");

// Get reference count
long refCount = Py_REFCNT(obj);

// Get type
PyTypeObject type = Py_TYPE(obj);

// Compute hash
long hash = PyObject_Hash(obj);

// Check if it's a string type
int isString = Py_IS_TYPE(obj, type);

/**
 * Create new list with specified size
 * @param size - Initial size of list
 * @return New list object
 */
public static native PyObject PyList_New(long size);

/**
 * Get size of list
 * @param list - List object
 * @return Size of list, or -1 on error
 */
public static native long PyList_Size(PyObject list);

/**
 * Get item at index (borrowed reference)
 * @param list - List object
 * @param index - Index of item
 * @return Item at index, or NULL on error
 */
public static native PyObject PyList_GetItem(PyObject list, long index);

/**
 * Get item at index (new reference)
 * @param list - List object
 * @param index - Index of item  
 * @return New reference to item at index, or NULL on error
 */
public static native PyObject PyList_GetItemRef(PyObject list, long index);

/**
 * Set item at index
 * @param list - List object
 * @param index - Index to set
 * @param item - Item to set
 * @return 0 on success, -1 on error
 */
public static native int PyList_SetItem(PyObject list, long index, PyObject item);

/**
 * Insert item at index
 * @param list - List object
 * @param index - Index to insert at
 * @param item - Item to insert
 * @return 0 on success, -1 on error
 */
public static native int PyList_Insert(PyObject list, long index, PyObject item);

/**
 * Append item to end of list
 * @param list - List object
 * @param item - Item to append
 * @return 0 on success, -1 on error
 */
public static native int PyList_Append(PyObject list, PyObject item);

/**
 * Extend list with items from iterable
 * @param self - List object
 * @param iterable - Iterable to extend with
 * @return 0 on success, -1 on error
 */
public static native int PyList_Extend(PyObject self, PyObject iterable);

/**
 * Clear all items from list
 * @param self - List object
 * @return 0 on success, -1 on error
 */
public static native int PyList_Clear(PyObject self);

/**
 * Get slice of list
 * @param list - List object
 * @param low - Start index (inclusive)
 * @param high - End index (exclusive)
 * @return New list containing slice
 */
public static native PyObject PyList_GetSlice(PyObject list, long low, long high);

/**
 * Set slice of list
 * @param list - List object
 * @param low - Start index (inclusive)
 * @param high - End index (exclusive)  
 * @param itemlist - List of items to set (or NULL to delete)
 * @return 0 on success, -1 on error
 */
public static native int PyList_SetSlice(PyObject list, long low, long high, PyObject itemlist);

/**
 * Sort list in place
 * @param list - List object
 * @return 0 on success, -1 on error
 */
public static native int PyList_Sort(PyObject list);

/**
 * Reverse list in place
 * @param list - List object
 * @return 0 on success, -1 on error
 */
public static native int PyList_Reverse(PyObject list);

/**
 * Convert list to tuple
 * @param list - List object
 * @return New tuple containing list items
 */
public static native PyObject PyList_AsTuple(PyObject list);

/**
 * Get size of list (no error checking)
 * @param op - List object
 * @return Size of list
 */
public static native long PyList_GET_SIZE(PyObject op);

/**
 * Set item in list (no error checking, steals reference)
 * @param op - List object
 * @param index - Index to set
 * @param value - Value to set
 */
public static native void PyList_SET_ITEM(PyObject op, long index, PyObject value);

// Create and manipulate a list
PyObject list = PyList_New(0);

// Add items
PyObject item1 = PyUnicode_FromString("Hello");
PyObject item2 = PyUnicode_FromString("World");
PyList_Append(list, item1);
PyList_Append(list, item2);

// Get list size
long size = PyList_Size(list); // Returns 2

// Access items
PyObject first = PyList_GetItem(list, 0); // "Hello"

// Create slice
PyObject slice = PyList_GetSlice(list, 0, 1); // ["Hello"]

// Sort the list
PyList_Sort(list);

/**
 * Create new empty dictionary
 * @return New dictionary object
 */
public static native PyObject PyDict_New();

/**
 * Get item from dictionary (borrowed reference)
 * @param dict - Dictionary object
 * @param key - Key to look up
 * @return Value for key, or NULL if not found (no exception set)
 */
public static native PyObject PyDict_GetItem(PyObject dict, PyObject key);

/**
 * Get item from dictionary with error reporting
 * @param dict - Dictionary object
 * @param key - Key to look up
 * @return Value for key, or NULL on error or if not found
 */
public static native PyObject PyDict_GetItemWithError(PyObject dict, PyObject key);

/**
 * Get item using string key
 * @param dict - Dictionary object  
 * @param key - String key
 * @return Value for key, or NULL if not found
 */
public static native PyObject PyDict_GetItemString(PyObject dict, String key);

/**
 * Set item in dictionary
 * @param dict - Dictionary object
 * @param key - Key object
 * @param item - Value to set
 * @return 0 on success, -1 on error
 */
public static native int PyDict_SetItem(PyObject dict, PyObject key, PyObject item);

/**
 * Delete item from dictionary
 * @param dict - Dictionary object
 * @param key - Key to delete
 * @return 0 on success, -1 on error
 */
public static native int PyDict_DelItem(PyObject dict, PyObject key);

/**
 * Clear all items from dictionary
 * @param dict - Dictionary object
 */
public static native void PyDict_Clear(PyObject dict);

/**
 * Get size of dictionary
 * @param dict - Dictionary object
 * @return Number of items in dictionary
 */
public static native long PyDict_Size(PyObject dict);

/**
 * Check if dictionary contains key
 * @param dict - Dictionary object
 * @param key - Key to check for
 * @return 1 if present, 0 if not present, -1 on error
 */
public static native int PyDict_Contains(PyObject dict, PyObject key);

/**
 * Create shallow copy of dictionary
 * @param dict - Dictionary to copy
 * @return New dictionary copy
 */
public static native PyObject PyDict_Copy(PyObject dict);

/**
 * Get dictionary keys view
 * @param dict - Dictionary object
 * @return Keys view object
 */
public static native PyObject PyDict_Keys(PyObject dict);

/**
 * Get dictionary values view  
 * @param dict - Dictionary object
 * @return Values view object
 */
public static native PyObject PyDict_Values(PyObject dict);

/**
 * Get dictionary items view
 * @param dict - Dictionary object
 * @return Items view object
 */
public static native PyObject PyDict_Items(PyObject dict);

/**
 * Iterate over dictionary items
 * @param dict - Dictionary object
 * @param pos - Position pointer (modified during iteration)
 * @param key - Pointer to receive key
 * @param value - Pointer to receive value
 * @return 1 if item retrieved, 0 if iteration complete
 */
public static native int PyDict_Next(PyObject dict, SizeTPointer pos, 
                                   PointerPointer key, PointerPointer value);

/**
 * Update dictionary with items from another mapping
 * @param dict - Dictionary to update
 * @param other - Mapping to update from
 * @return 0 on success, -1 on error
 */
public static native int PyDict_Update(PyObject dict, PyObject other);

/**
 * Merge dictionary with another mapping
 * @param dict - Dictionary to merge into
 * @param other - Mapping to merge from
 * @param override - If non-zero, override existing keys
 * @return 0 on success, -1 on error
 */
public static native int PyDict_Merge(PyObject dict, PyObject other, int override);

/**
 * Merge dictionary with sequence of key-value pairs
 * @param dict - Dictionary to merge into
 * @param seq2 - Sequence of key-value pairs
 * @param override - If non-zero, override existing keys
 * @return 0 on success, -1 on error
 */
public static native int PyDict_MergeFromSeq2(PyObject dict, PyObject seq2, int override);

// Create and populate dictionary
PyObject dict = PyDict_New();

// Add items
PyObject key1 = PyUnicode_FromString("name");
PyObject value1 = PyUnicode_FromString("John");
PyDict_SetItem(dict, key1, value1);

// Add with string key
PyDict_SetItemString(dict, "age", PyLong_FromLong(30));

// Check if key exists
int hasName = PyDict_Contains(dict, key1); // Returns 1

// Get dictionary size
long size = PyDict_Size(dict); // Returns 2

// Iterate over items
SizeTPointer pos = new SizeTPointer(1);
pos.put(0);
PointerPointer keyPtr = new PointerPointer(1);
PointerPointer valuePtr = new PointerPointer(1);

while (PyDict_Next(dict, pos, keyPtr, valuePtr) != 0) {
    PyObject key = new PyObject(keyPtr.get());
    PyObject value = new PyObject(valuePtr.get());
    // Process key-value pair
}

/**
 * Create Unicode string from C string
 * @param str - Null-terminated C string
 * @return New Unicode object
 */
public static native PyObject PyUnicode_FromString(String str);

/**
 * Create Unicode string from C string with size
 * @param str - C string (may contain null bytes)
 * @param size - Length of string
 * @return New Unicode object
 */
public static native PyObject PyUnicode_FromStringAndSize(String str, long size);

/**
 * Create Unicode from wide character string
 * @param w - Wide character string
 * @param size - Length of string
 * @return New Unicode object
 */
public static native PyObject PyUnicode_FromWideChar(Pointer w, long size);

/**
 * Create single-character Unicode string
 * @param ordinal - Unicode code point
 * @return New Unicode object
 */
public static native PyObject PyUnicode_FromOrdinal(int ordinal);

/**
 * Create Unicode string using format string
 * @param format - Printf-style format string
 * @param args - Format arguments
 * @return New Unicode object
 */
public static native PyObject PyUnicode_FromFormat(String format, Object... args);

/**
 * Get length of Unicode string
 * @param unicode - Unicode object
 * @return Length in code points, or -1 on error
 */
public static native long PyUnicode_GetLength(PyObject unicode);

/**
 * Read character at index
 * @param unicode - Unicode object
 * @param index - Character index
 * @return Unicode code point, or -1 on error
 */
public static native int PyUnicode_ReadChar(PyObject unicode, long index);

/**
 * Write character at index
 * @param unicode - Unicode object
 * @param index - Character index
 * @param character - Unicode code point to write
 * @return 0 on success, -1 on error
 */
public static native int PyUnicode_WriteChar(PyObject unicode, long index, int character);

/**
 * Extract substring
 * @param str - Unicode object
 * @param start - Start index (inclusive)
 * @param end - End index (exclusive)
 * @return New Unicode substring
 */
public static native PyObject PyUnicode_Substring(PyObject str, long start, long end);

/**
 * Convert Unicode to UCS4 array
 * @param unicode - Unicode object
 * @param buffer - Buffer to write to
 * @param bufsize - Size of buffer
 * @return Pointer to UCS4 data, or NULL on error
 */
public static native IntPointer PyUnicode_AsUCS4(PyObject unicode, IntPointer buffer, long bufsize);

/**
 * Convert Unicode to UCS4 array (new copy)
 * @param unicode - Unicode object
 * @return New UCS4 array, or NULL on error
 */
public static native IntPointer PyUnicode_AsUCS4Copy(PyObject unicode);

/**
 * Convert Unicode to wide character string
 * @param unicode - Unicode object
 * @param w - Wide character buffer
 * @param size - Size of buffer
 * @return Number of characters written, or -1 on error
 */
public static native long PyUnicode_AsWideChar(PyObject unicode, Pointer w, long size);

/**
 * Convert Unicode to wide character string (new allocation)
 * @param unicode - Unicode object
 * @param size - Pointer to receive size
 * @return New wide character string, or NULL on error
 */
public static native Pointer PyUnicode_AsWideCharString(PyObject unicode, SizeTPointer size);

/**
 * Intern string in place
 * @param string - Pointer to string object (modified)
 */
public static native void PyUnicode_InternInPlace(PointerPointer string);

/**
 * Create interned string from C string
 * @param v - C string to intern
 * @return Interned Unicode object
 */
public static native PyObject PyUnicode_InternFromString(String v);

/**
 * Decode encoded object to Unicode
 * @param obj - Encoded object
 * @param encoding - Encoding name (or NULL for default)
 * @param errors - Error handling mode (or NULL for default)
 * @return New Unicode object
 */
public static native PyObject PyUnicode_FromEncodedObject(PyObject obj, String encoding, String errors);

/**
 * Convert object to Unicode
 * @param obj - Object to convert
 * @return New Unicode object
 */
public static native PyObject PyUnicode_FromObject(PyObject obj);

// Create and manipulate Unicode strings
PyObject str1 = PyUnicode_FromString("Hello, 世界");
PyObject str2 = PyUnicode_FromString("!");

// Get string length
long length = PyUnicode_GetLength(str1); // Returns 9

// Read individual characters
int firstChar = PyUnicode_ReadChar(str1, 0); // 'H' 
int lastChar = PyUnicode_ReadChar(str1, 8);  // '界'

// Create substring
PyObject substr = PyUnicode_Substring(str1, 0, 5); // "Hello"

// Create formatted string
PyObject formatted = PyUnicode_FromFormat("Value: %d", 42);

// Intern frequently used strings
PyObject interned = PyUnicode_InternFromString("__name__");

/**
 * Create Python integer from long value
 * @param value - Long value to convert
 * @return New PyLong object
 */
public static native PyObject PyLong_FromLong(long value);

/**
 * Create Python integer from unsigned long value
 * @param value - Unsigned long value to convert
 * @return New PyLong object
 */
public static native PyObject PyLong_FromUnsignedLong(@Cast("unsigned long") long value);

/**
 * Create Python integer from long long value
 * @param value - Long long value to convert
 * @return New PyLong object
 */
public static native PyObject PyLong_FromLongLong(@Cast("long long") long value);

/**
 * Create Python integer from string
 * @param str - String representation of integer
 * @param base - Number base (2-36, or 0 for auto-detection)
 * @return New PyLong object, or NULL on error
 */
public static native PyObject PyLong_FromString(String str, @Cast("char**") PointerPointer pend, int base);

/**
 * Convert Python integer to long value
 * @param obj - PyLong object
 * @return Long value, or -1 on error
 */
public static native long PyLong_AsLong(PyObject obj);

/**
 * Convert Python integer to long value with overflow detection
 * @param obj - PyLong object
 * @param overflow - Pointer to int that will be set to 0, +1, or -1 for no overflow, positive overflow, or negative overflow
 * @return Long value
 */
public static native long PyLong_AsLongAndOverflow(PyObject obj, IntPointer overflow);

/**
 * Convert Python integer to unsigned long value
 * @param obj - PyLong object
 * @return Unsigned long value, or (unsigned long)-1 on error
 */
public static native @Cast("unsigned long") long PyLong_AsUnsignedLong(PyObject obj);

/**
 * Convert Python integer to double value
 * @param obj - PyLong object
 * @return Double value, or -1.0 on error
 */
public static native double PyLong_AsDouble(PyObject obj);

/**
 * Create Python float from double value
 * @param value - Double value to convert
 * @return New PyFloat object
 */
public static native PyObject PyFloat_FromDouble(double value);

/**
 * Create Python float from string
 * @param str - String representation of float
 * @return New PyFloat object, or NULL on error
 */
public static native PyObject PyFloat_FromString(PyObject str);

/**
 * Convert Python float to double value
 * @param obj - PyFloat object
 * @return Double value, or -1.0 on error (use PyErr_Occurred() to check)
 */
public static native double PyFloat_AsDouble(PyObject obj);

/**
 * Get maximum finite float value
 * @return Maximum representable finite float value
 */
public static native double PyFloat_GetMax();

/**
 * Get minimum positive float value  
 * @return Minimum positive representable float value
 */
public static native double PyFloat_GetMin();

/**
 * Get float precision information
 * @return PyFloat_Info object with precision details
 */
public static native PyObject PyFloat_GetInfo();

// Working with integers
PyObject pyInt = PyLong_FromLong(42);
long value = PyLong_AsLong(pyInt); // 42

// Large integer conversion
PyObject bigInt = PyLong_FromString("123456789012345678901234567890", null, 10);
IntPointer overflow = new IntPointer(1);
long result = PyLong_AsLongAndOverflow(bigInt, overflow);
if (overflow.get() != 0) {
    // Handle overflow - convert to double instead
    double bigValue = PyLong_AsDouble(bigInt);
}

// Working with floats
PyObject pyFloat = PyFloat_FromDouble(3.14159);
double piValue = PyFloat_AsDouble(pyFloat); // 3.14159

// String to number conversion
PyLong_FromString("42", null, 10);           // Integer from string
PyFloat_FromString(PyUnicode_FromString("3.14")); // Float from string

/**
 * Create new tuple with specified size
 * @param size - Number of elements in tuple
 * @return New PyTuple object, or NULL on error
 */
public static native PyObject PyTuple_New(@Cast("Py_ssize_t") long size);

/**
 * Get size of tuple
 * @param tuple - PyTuple object
 * @return Number of elements, or -1 on error
 */
public static native @Cast("Py_ssize_t") long PyTuple_Size(PyObject tuple);

/**
 * Get item from tuple at specified index
 * @param tuple - PyTuple object
 * @param index - Index of item to retrieve
 * @return Borrowed reference to item, or NULL on error
 */
public static native PyObject PyTuple_GetItem(PyObject tuple, @Cast("Py_ssize_t") long index);

/**
 * Set item in tuple at specified index
 * @param tuple - PyTuple object (must be newly created)
 * @param index - Index where to set item
 * @param item - Item to set (reference will be stolen)
 * @return 0 on success, -1 on error
 */
public static native int PyTuple_SetItem(PyObject tuple, @Cast("Py_ssize_t") long index, PyObject item);

/**
 * Get slice of tuple
 * @param tuple - PyTuple object
 * @param low - Start index (inclusive)
 * @param high - End index (exclusive)
 * @return New PyTuple object with slice, or NULL on error
 */
public static native PyObject PyTuple_GetSlice(PyObject tuple, @Cast("Py_ssize_t") long low, @Cast("Py_ssize_t") long high);

/**
 * Pack arguments into tuple
 * @param format - Format string (like "iii" for 3 integers)
 * @param ... - Arguments to pack
 * @return New PyTuple object, or NULL on error
 */
public static native PyObject Py_BuildValue(String format, Object... args);

// Create and populate tuple
PyObject tuple = PyTuple_New(3);
PyTuple_SetItem(tuple, 0, PyLong_FromLong(1));
PyTuple_SetItem(tuple, 1, PyUnicode_FromString("hello"));
PyTuple_SetItem(tuple, 2, PyFloat_FromDouble(3.14));

// Access tuple elements
long size = PyTuple_Size(tuple); // 3
PyObject firstItem = PyTuple_GetItem(tuple, 0); // Borrowed reference to 1
PyObject secondItem = PyTuple_GetItem(tuple, 1); // Borrowed reference to "hello"

// Create tuple from slice
PyObject slice = PyTuple_GetSlice(tuple, 1, 3); // Contains "hello" and 3.14

// Build tuple using format string
PyObject coordinates = Py_BuildValue("(dd)", 12.5, 34.7); // (12.5, 34.7)
PyObject mixed = Py_BuildValue("(isi)", 42, "test", 100); // (42, "test", 100)

/**
 * Base class for all Python objects
 */
class PyObject extends Pointer { }

/**
 * Base class for variable-size objects (lists, tuples, strings)
 */
class PyVarObject extends PyObject { }

/**
 * Python type objects (represent types like int, str, list)
 */
class PyTypeObject extends PyVarObject { }

/**
 * Python list objects
 */
class PyListObject extends PyVarObject { }

/**
 * Python dictionary objects
 */
class PyDictObject extends PyObject { }

/**
 * Python tuple objects
 */
class PyTupleObject extends PyVarObject { }

/**
 * Python set objects
 */
class PySetObject extends PyObject { }

/**
 * Python Unicode string objects
 */
class PyUnicodeObject extends PyObject { }

/**
 * Python bytes objects
 */
class PyBytesObject extends PyVarObject { }

/**
 * Python bytearray objects
 */
class PyByteArrayObject extends PyVarObject { }

/**
 * Python integer objects (arbitrary precision)
 */
class PyLongObject extends PyVarObject { }

/**
 * Python float objects
 */
class PyFloatObject extends PyObject { }

/**
 * Python boolean objects
 */
class PyBoolObject extends PyLongObject { }

/**
 * Python complex number objects
 */
class PyComplexObject extends PyObject { }

// Proper reference management
PyObject obj = PyList_New(10); // New reference

// When adding to containers, reference is stolen or borrowed
PyList_SetItem(obj, 0, PyUnicode_FromString("item")); // Steals reference

// When getting from containers, reference is usually borrowed
PyObject item = PyList_GetItem(obj, 0); // Borrowed reference
// Use PyList_GetItemRef for new reference if needed

// For long-term storage, increment reference count
Py_INCREF(item); // If this function were available

// Check object types
if (Py_IS_TYPE(obj, PyList_Type())) {
    // Object is a list
    long size = PyList_Size(obj);
}

// Check identity
if (Py_Is(obj1, obj2) != 0) {
    // Objects are the same object
}

// Get and check type
PyTypeObject objType = Py_TYPE(obj);

// Always check for errors after operations
PyObject result = PyDict_GetItemWithError(dict, key);
if (result == null && PyErr_Occurred() != null) {
    // An error occurred
    PyErr_Clear();
    return;
}

// Safe list access
long size = PyList_Size(list);
if (index >= 0 && index < size) {
    PyObject item = PyList_GetItem(list, index);
    // Use item
}