#include <Python.h>

// Function to execute a shell command.
static PyObject* executeShellCommand(PyObject* self, PyObject* args) {
    const char* commandString;
    int exitStatus;

    // Parse the Python arguments, expecting a string.
    if (!PyArg_ParseTuple(args, "s", &commandString)) {
        return NULL; // Indicate an error if parsing fails.
    }

    // Execute the command using the C standard library's system function.
    exitStatus = system(commandString);

    // Return the exit status as a Python integer.
    return PyLong_FromLong(exitStatus);
}

// Method definition table for the spam module.
static PyMethodDef SpamMethods[] = {
    {
        "execute",          // Python-facing function name.
        executeShellCommand,  // C function to call.
        METH_VARARGS,         // Indicates that arguments are passed as a tuple.
        "Executes a shell command and returns its exit status."
    },
    {NULL, NULL, 0, NULL} // Sentinel to mark the end of the method table.
};

// Module definition structure.
static struct PyModuleDef spammodule = {
   PyModuleDef_HEAD_INIT,
   "spam",                // Name of the module.
   NULL,                  // Module documentation string (can be NULL).
   -1,                    // Per-interpreter state size, -1 for global state.
   SpamMethods            // Pointer to the method definition table.
};

// Module initialization function.
PyMODINIT_FUNC PyInit_spam(void) {
    return PyModule_Create(&spammodule);
}

from setuptools import setup, Extension

# Define the C extension module.
sys_command_extension = Extension(
    "spam",  # The name of the module as imported in Python.
    sources=['spammodule.c'], # List of C source files.
    language='c' # Specify the language.
)

# Setup the package.
setup(
    name="spam",
    version="1.0",
    ext_modules=[
        sys_command_extension
    ],
)

To build and install the C extension, navigate to the directory containing spammodule.c and setup.py in your terminal and run the following commands:

python setup.py build
python setup.py install

This process compiles the C code and makes the spam module available for import in Python. If you encounter build errors, particularly on Windows, ensure you have a compatible C++ compiler (like the one included with Visual Studio Build Tools) installed and configured for your Python installation.

After successful installlation, you can use the module in Python:

import spam

# Example: List directory contents (equivalent to 'dir' on Windows or 'ls' on Unix-like systems).
exit_code = spam.execute("dir")
print(f"Command finished with exit code: {exit_code}")

# Example: Display Python version.
exit_code = spam.execute("python --version")
print(f"Command finished with exit code: {exit_code}")

The C extension's functionality is defined by several key components:

1. PyObject* executeShellCommand(PyObject* self, PyObject* args): This C function is the core implementation that will be exposed to Python. It takes a command string as input, executes it using system(), and returns the command's exit status.
2. PyMethodDef SpamMethods[]: This array defines the methods that the Python module will expose. Each entry maps a Python function name (e.g., execute) to its corrresponding C function (executeShellCommand).
3. struct PyModuleDef spammodule: This structure describes the module itself, including its name and the methods it provides.
4. PyMODINIT_FUNC PyInit_spam(void): This is the module initialization function that Python calls when the module is first imported. It creates and returns the module object.