La verdad, me parece una documentación un poco vaga la que ofrecen en ese modulo.
Que hace **
Esto no es particular de este modulo. Es una caracteristica de Python.
La funcionalidad del **
en las funciones la explico en esta respuesta: ¿Qué significa (*variable) en Python?
Citaré la parte relevante por si el link se cae:
Por otro lado, al hacer lo mismo con ** hace que la función acepte
infinitos argumentos, pero hay que aclarar primero el nombre del
argumento. Por ejemplo def func(hola, **kargs)
. Si llamas a esta
función asi func(0, key=1)
va a funcionar, pero no funcionará
func(0, 1)
. Lo que encontrarás dentro de kargs, será un diccionario
con los argumentos ingresados. En el caso del ejemplo, sería
{'key':1}
.
Que keyword args acepta Secs
Bueno, como podrás ver, **options
acepta infinitos argumentos cuyos nombres pueden ser cualquiera. Por diversos motivos puede suceder un error si se pasan keyword args de más (un error creado por el propio modulo, que internamente estos argumentos sean pasados a una función que solo acepta ciertos keyword args, etc).
Como en la documentación de help
no se indica que keyboard args acepta options, no nos queda de otra que revisar el código fuente de Secs:
class Secs:
"""
Seconds class
"""
# Default options
abbrev = False
def __new__(cls, time, **options):
"""
Set the time to convert and the output options.
...
Parameters
----------
time
The time that will be converted.
options
The options that control the output.
Raises
------
TypeError
if time isn't a String or an Integer.
"""
if not isinstance(time, (str, int)): #or not isinstance(time, int):
raise TypeError(f"time must be a String or an Integer in \"{inspect.currentframe().f_code.co_name}\".")
else:
# Get options
if "abbrev" in options:
# Raise error if abbrev isn't a Boolean.
if not isinstance(options["abbrev"], bool):
raise TypeError(
"abbrev must be a Boolean in options parameter in options parameter in \"{inspect.currentframe)(.f_code.co_name)}\".")
else:
cls.abbrev = options["abbrev"]
return cls.convert(cls, time)
Y analizandolo, nos damos cuenta que el unico keyword arg usado realmente es un booleano llamado abbrev
. Puedes pasarle cualquier otra cosa sin efectos negativos, pero el código no lo usaría.
En que afecta el argumento abbrev
Esto no está documentado oficialmente, pero en un ejemplo:
# Lets import Secs class from Seconds Package
from seconds import Secs
# Lets pass 5 minutes to seconds and seconds to 10 minutes
Secs("5m") # => 300
Secs(600) # => 10 minutes
# But we want to abbreviate our minutes so we
# will pass the abbrev parameter to options
Secs(600, abbrev=True) # => 10m
# Lets pass 6 months to seconds and then pass 1 year to seconds
Secs("6mo") # => 110451600
Secs("1y") # => 220903200
Parece que escribe una forma abreviada. Es decir, minutes lo transforma en m, hour en h, etc.
Sin embargo, con más pruebas, parece que Secs devuelve la versión abreviada por default y esto se puede deshabilitar con abbrev=True, contradiciendo los comentarios en el ejemplo en el repositorio.
Es más, las pruebas y los analisis al código fuente me indicaron que el valor default de abbrev es cambiado cada vez que llamas a Secs.
Ejemplo:
from seconds import Secs
# abbrev = False (devuelve abreviado)
print(Secs(3600))
# abbrev = True (devuelve sin abreviar)
print(Secs(3600, abbrev=True))
# abbrev = True (devuelve sin abreviar)
print(Secs(3600))
Produce:
1h
1 hour
1 hour
Documentación no oficial basada en este analisis
Secs acepta un argumento opcional llamado abbrev que:
- Su valor default se establece al valor que le pases cada vez que llames a Secs (confuso, verdad?)
- Si es True, devuelve la versión sin abreviar
- Si es False, devuelve la versión abreviada
Mi opinión, este modulo no está bien hecho, es confuso y es seguro que el autor no lo diseñó como pensaba ni hizo las pruebas adecuadas para asegurarse de que funcione bien. Te recomiendo recurrir a otro modulo, o hacer el tuyo propio.
Que es self
Debido a una duda que presentas en los comentarios, me dedicaré a explicar que es self.
Imagina que tenemos el siguiente código:
class Vehiculo:
def __init__(self, tipo):
self.tipo = tipo
def print(self, ruedas):
print(f"El vehiculo {self.tipo}' tiene {ruedas} ruedas")
auto = Vehiculo("auto")
auto.print(4)
Cuando esta linea se ejecuta auto.print(4)
internamente se hace Vehiculo.print(auto, 4)
. Ese es el primer argumento que recibe la función print. Por convenio, ese argumento es llamado self
.
Normalmente, este proceso es automático, por lo que no suele ser necesario pasar el argumento self.
Cuando llamas a una clase como sucede en esta linea: Vehiculo("auto")
, lo normal es que se devuelva un objeto especial relacionado con la clase Vehiculo. Ese objeto se llama instancia
. Y la acción de crear una instancia, se llama instanciar
.
Cuando ejecutas Vehiculo.print() te están faltando dos argumentos, self, que en este caso no se pasa automaticamente (ese argumento se agrega automaticamente solo cuando el método (función dentro de una clase) es llamado desde una instancia) y ruedas.
Como influye esto en el módulo
En este caso, debido a como está hecho un método especial llamado __new__
, resulta imposible (sin alterar el código original) de instanciar a Secs. Intentar instanciar a Secs resultará en obtener un entero o una cadena.
Parece que el uso de convert y pluralize es de proposito interno. Y en el caso particular de este módulo, cada vez que estos métodos son llamados, self resulta ser Secs (pero la clase, no la instancia).
Aun así, si insistes en usarlos puedes hacerlo así:
Secs.convert(Secs, [el tiempo a convertir])
El error NameError
El error NameError ocurre cuando recurres a una variable, pero Python no la encuentra por ningún lado.
Ejemplo:
def a():
def b():
c()
b()
a()
En este caso, cuando la función b se ejecuta, busca la variable c dentro de b, luego dentro de a, luego fuera de toda función. Y como no la encuentra, ocurre el siguiente error:
NameError: name 'c' is not defined
Eso es lo que te pasó con self.