Código Python: kardex con promedio ponderado (descarga gratis)

Código Python: kardex con promedio ponderado (descarga gratis)

Se vendió mercancía y el costo de lo que salió del depósito hay que escribirlo hoy, no al cerrar el mes. Cuando el precio de compra cambió dos veces en la misma semana, esa cuenta hecha de memoria falla. Este programa de Python lee las compras y las ventas de un archivo, recalcula el costo promedio ponderado después de cada movimiento y deja la tabla lista para revisar o para pasar a contabilidad. Le sirve al dueño que quiere entender de dónde sale el costo que aparece en el margen, a la persona de bodega que entrega la mercancía y al contador que necesita el detalle sin reconstruirlo a mano.

No es un sistema de inventarios ni una aplicación con pantallas: es un archivo de texto con instrucciones que se pueden leer, ejecutar y modificar. Viene con datos de ejemplo de dos productos de una ferretería, el cemento y el cable, para que el resultado se entienda sin haber preparado nada antes.

Qué trae el paquete

El ZIP pesa 5427 bytes y se descomprime en una sola carpeta. Adentro está todo: el programa comentado, los datos de ejemplo, la salida que debe obtenerse y una guía corta. No hay que instalar dependencias ni crear cuentas en ningún sitio.

Qué hace el programa

El recorrido es el de un kardex de papel, en el mismo orden en que ocurrieron los hechos:

1. Lee datos/movimientos.csv. Cada fila trae la fecha, el producto, el tipo de movimiento, la cantidad, el costo unitario y el detalle del documento.
2. Agrupa los movimientos por producto y los recorre respetando el orden del archivo.
3. En cada compra sube las unidades del saldo y suma al inventario el valor que realmente se pagó.
4. Después de cada movimiento recalcula el costo promedio: el valor del saldo dividido entre las unidades que quedan.
5. En cada venta valora la mercancía con el promedio vigente antes de descontarla del saldo.
6. Imprime el kardex en columnas, arma el resumen por producto con su comprobación y guarda todo en salida/kardex.csv.

Cómo ejecutarlo

Se necesita Python 3.11 o superior y nada más: el programa usa solo la biblioteca estándar, así que no hay paquetes por instalar ni licencias por pagar. Los pasos son estos.

1. Instalar Python desde el sitio oficial, marcando la casilla que lo agrega al sistema.
2. Descomprimir el ZIP en una carpeta cualquiera.
3. Abrir la terminal y ubicarse en esa carpeta, con el comando que cambia de directorio.
4. Escribir la orden y pulsar Enter.

python kardex_promedio.py

Aparece la tabla en la ventana y, al final, el aviso del archivo generado. El CSV queda en salida/kardex.csv, dentro de la misma carpeta, y se abre con Excel o con cualquier planilla de cálculo. Un detalle que ahorra tiempo: el programa se ubica solo, porque toma como referencia la carpeta del archivo del programa, así que se puede ejecutar desde cualquier ruta y siempre escribirá el resultado junto a sí mismo.

El código, explicado

El programa no llega a doscientas líneas y está comentado línea por línea. Estas cinco partes son las que conviene entender, porque son las que deciden el costo.

Uno: el dinero no se calcula con decimales binarios. Los centavos se manejan con Decimal, no con float, y cada resultado se redondea a dos decimales con el redondeo comercial. Es la diferencia entre un kardex que cuadra y uno que arrastra centavos perdidos.

def redondear(valor: Decimal) -> Decimal:
    """Redondea a dos decimales (centavos) con el redondeo comercial."""
    return valor.quantize(CENTAVO, rounding=ROUND_HALF_UP)

Dos: cada compra entra por lo que se pagó de verdad. El estado del producto guarda tres cosas: las unidades, el valor y la lista de filas que se van a imprimir. En una entrada, la cantidad sube, el valor pagado se suma y la fila se llena con los datos de la compra.

        if movimiento["tipo"] == TIPO_ENTRADA:
            # Entrada: el inventario sube por lo que realmente se pagó.
            costo = Decimal(movimiento["costo_unitario"])
            valor = redondear(cantidad * costo)
            estado["cantidad"] += cantidad
            estado["valor"] += valor
            fila.update(e_cant=cantidad, e_vu=costo, e_val=valor)

Tres: la venta se valora con el promedio anterior al movimiento. Aquí está el corazón del promedio ponderado y el orden importa: el promedio se calcula con el saldo que había antes de descontar la venta. Si se calculara después, la salida quedaría valorada con un costo que todavía no existía y el margen se vería distinto del real.

        elif movimiento["tipo"] == TIPO_SALIDA:
            # Salida: se valora al promedio vigente ANTES de descontar el movimiento.
            promedio = redondear(estado["valor"] / estado["cantidad"]) if estado["cantidad"] else Decimal("0.00")
            valor = redondear(cantidad * promedio)
            estado["cantidad"] -= cantidad
            estado["valor"] -= valor
            fila.update(s_cant=cantidad, s_vu=promedio, s_val=valor)

Cuatro: el saldo se recalcula con cada movimiento. Terminado el movimiento, el programa deja en la fila el saldo en unidades, el promedio del saldo y el valor del saldo. El promedio que se imprime va redondeado a centavos, pero el valor del saldo conserva la suma real: por eso el kardex no pierde centavos cuando se compara con la contabilidad.

        fila["saldo_cant"] = estado["cantidad"]
        # # Costo promedio vigente: valor del saldo entre las unidades del saldo
        fila["saldo_prom"] = redondear(estado["valor"] / estado["cantidad"]) if estado["cantidad"] else Decimal("0.00")
        fila["saldo_val"] = redondear(estado["valor"])

Cinco: la comprobación avisa si algo no cuadra. El resumen suma entradas y salidas de cada producto y compara: si el saldo es igual a las entradas menos las salidas, imprime CUADRA; si no, REVISAR. Es la alarma más barata que se puede tener en un inventario.

        cuadra = entradas_cant - salidas_cant == estado["cantidad"]
        print(f"  {producto}")
        print(f"    Entradas : {miles(entradas_cant):>9} unidades {miles(entradas_val):>16}")
        print(f"    Salidas   : {miles(salidas_cant):>9} unidades {miles(salidas_val):>16}")
        print(f"    Saldo       : {miles(estado['cantidad']):>9} unidades {miles(redondear(estado['valor'])):>16}")
        print(f"    Comprobación (saldo = entradas - salidas): {'CUADRA' if cuadra else 'REVISAR'}")

Con esas cinco piezas ya se puede leer el programa completo. Si más adelante hace falta, se puede agregar una columna al CSV y usar el campo libre para la bodega o el proveedor, sin tocar el cálculo.

Qué vas a ver en pantalla

La primera pantalla repite el encabezado del programa, avisa cuántos movimientos leyó y abre la tabla del primer producto. Se ve así:

================================================================================================================================================================
  KARDEX CON PROMEDIO PONDERADO
  Código Python didáctico · Kardex Tauro · kardex-tauro.muisca.co
================================================================================================================================================================
Movimientos leídos: 10

Producto: Cemento gris 50 kg
----------------------------------------------------------------------------------------------------------------------------------------------------------------
Fecha       Detalle                                         Entrada   V. unit. Valor entrada   Salida   C. prom.  Costo ventas    Saldo   C. prom.   Valor saldo

De izquierda a derecha: la fecha, el detalle del documento, la cantidad y el costo unitario de la compra, el valor de esa entrada, la cantidad y el costo promedio de la venta, el costo de ventas, el saldo en unidades y el valor del saldo con su promedio. Los renglones de compra y de venta se distinguen porque las columnas que no aplican quedan vacías. Al final de cada producto aparece el saldo final, y después el resumen con la comprobación. En los datos de ejemplo el cemento arranca con una compra de 100 unidades a 18 000 cada una, luego una venta de 90 unidades y una segunda compra a 20 000: ahí se ve cómo el promedio sube y cómo la siguiente venta sale valorada con el promedio nuevo, no con el precio de la primera compra.

Errores comunes y consejos

• El tipo de movimiento debe decir exactamente Compra o Venta. El programa no adivina: si encuentra otra palabra, se detiene con un mensaje en vez de seguir calculando mal.
• Si se edita el CSV en Excel, hay que guardarlo como CSV delimitado por comas y conservar los nombres de las columnas, porque el programa los usa para leer cada dato.
• Las fechas se escriben con año, mes y día, por ejemplo 2026-03-02. El programa no reordena el archivo: un movimiento fuera de fecha queda en el kardex en ese mismo orden.
• Si una venta deja el saldo en cero, el promedio se calcula solo cuando hay unidades; la condición que evita dividir entre cero ya está escrita dentro del programa.
• Cuando el resumen imprime REVISAR, casi siempre hay un costo unitario mal escrito o un movimiento con el tipo cambiado. Vale la pena revisar esas dos columnas antes que el resto.
• El CSV de salida se puede copiar y ampliar con más productos: el programa arma un bloque por producto sin tocar el código.

Cuándo esto no alcanza

Conviene decir con claridad qué resuelve este programa y qué no. Resuelve el cálculo del promedio ponderado sobre un archivo limpio y enseña por qué el orden de los movimientos cambia el costo de ventas, pero no controla quién digita, no cruza la factura con la remisión, no maneja varias bodegas ni avisa cuando un costo quedó sospechosamente alto. Tampoco guarda un histórico de cambios.

Cuando el negocio ya no quiere depender de un archivo que una sola persona mantiene, el paso siguiente es Kardex Tauro, un programa para el inventario del día a día en el que el mismo cálculo ocurre sin que nadie tenga que ejecutar nada. Mientras el volumen sea bajo y una sola persona maneje los movimientos, este código es más que suficiente: es gratis y se puede leer completo.

Descargue el paquete, ejecútelo con los datos de ejemplo y después reemplace el archivo de movimientos por los suyos. Ver el propio inventario en una tabla que cuadra es la mejor forma de entender el promedio ponderado. Y si el resultado le sirve, guárdelo: Kardex Tauro publica más programas didácticos como este.