Common Options

Several options for command execution are available in all modes.

Output format

Normally, the generated objects are output as is with print(), but the output format can be changed by using the following options.

  • --repr: The generated object is converted by using repr() before output.

  • --json: Outputs the generated object in JSON format. Objects for which no standard JSON format is defined are converted to JSON after being converted to strings with str().

  • --json-indent <INDENT>: If specified with --json, the output JSON will be formatted with the specified indent. Examples of INDENT: 2 (two spaces), \t (a tab character), etc.

  • --json-ensure-ascii: If specified with --json, the output JSON will be escaped unicode.

For example:

randog time --repr

randog time --json
randog byfile def.py --json --json-indent 2
randog byfile def.py --json --json-indent \t
randog str --charset あいう --length 5 --json --json-ensure-ascii

Output to file

--output option can be used to output to a file, as in the following example.

# output to ./out.txt; if already exists, it will be truncated
randog time --output ./out.txt

# output to ./out.txt;
# if already exists, it will be kept and generated values will be appended at the end of the file
randog time --output ./out.txt --output-appending

# output to out.txt in UTF-16 LE with line-separator '\r\n'
randog byfile ./factory_def.py -O out.txt -X utf_16_le --O-ls CRLF

# {now} will be replaced by the current time
randog time --output './out_{now:%Y%m%d%H%M%S}.txt'

As above examples, by default, the file specified as the output destination is truncated if it already exists, but you can append it to the end of an existing file by using the option --output-appending (--Oa).

As above examples, You can specify the encoding and newline character for output with options --output-encoding (-X) and --output-linesep (--O-ls). In byfile mode, you can also define encoding and newline character in External File Definition of Factory.

As the examples above also uses {now}, the following placeholders can be used with format specification.

  • {0} (int):

    Serial number, which is a sequential number when the --repeat option is used or when multiple definition files are used in order in byfile mode. If used only once, {} is also acceptable.

  • {def_file} (str):

    The name of the definition file used in byfile mode; however, the trailing .py is removed. It is replaced by an empty string except in byfile mode.

  • {repeat_count} (int):

    Sequential numbers for repeating with the --repeat option. If --repeat is not used, it is replaced by 0.

  • {factory_count} (int):

    Sequential number assigned to each definition file when using multiple definition files in byfile mode. If in except in byfile mode, it is replaced by 0.

  • {now} (datetime.datetime):

    Current datetime.

  • (environment variables):

    Environment variables can be used as placeholders, such as {HOME}.

Iteration

There are two types of repeat generation options: --list (-L) and --repeat (-r).

If you want to output repeatedly generated objects in a single list, use --list as follows:

# generate ONE list which contains 3 objects; each element conforms to factory_def.py.
randog byfile factory_def.py --list 3

On the other hand, if you want to output each repeatedly generated object separately, use --repeat as follows:

# generate and output 3 times
randog byfile factory_def.py --repeat 3

Note

If you want to output to different files one at a time using --repeat, use --output with a placeholder as follows:

# output to 'out_1.txt', 'out_2.txt', and 'out_3.txt'
randog factory_def.py --repeat 3 --output './out_{}.txt'

# output to 'out_0001.txt', 'out_0002.txt', and 'out_0003.txt'
randog factory_def.py --repeat 3 --output './out_{:04}.txt'

The rules for placeholders are the same as the standard python format.

See Output to file for available placeholders.

Seed

Normally, the values are generated randomly, but if you want to control the output results, use --seed to specify a seed value. If the seed values are the same, as in the following example, the same result is returned.

# first
randog str --seed 42

# second; the result is the same as the first
randog str --seed 42

Warning

Even though the seed value is the same, the generated value may change if the python version changes. See also the document of reproducibility.

Also, version upgrades of randog and dependent packages may change the generated values.

If no seed value is specified, a random seed value is used. The seed value used is logged out so that the seed value can be checked as follows:

# generate str with log
randog str --log-stderr DEBUG

If you note the observed seed value, you can reproduce the generation the next time by using that seed value.

Convert to pickle

Output data can be converted to pickle by using the --pickle option as shown below.

# output generated value as pickle into file
randog date --pickle --output out.pickle

The above example outputs binary to file, but it can also be output as a string by combining with --base64 or --fmt. You can use the formatting codes of bytes mode when using --fmt.

# output generated value as pickle in hex
randog date --pickle --fmt 'x'

# output generated value as pickle in base64
randog date --pickle --base64

Modify environment variable

In particular, in byfile mode, you may want to specify environment variables for the purpose of passing values to the definition file. In bash and other shells, you can specify environment variables on a single line, such as VAR=VAL randog ..., but this is not possible in some shells, such as powershell.

Therefore, randog provides an option to specify environment variables. You can specify environment variables by using --env as follows:

randog byfile factory_def.py --env CHARSET=0123456789abcdef

The above mentioned execution is useful, for example, when using a definition file such as the following:

import os
import randog.factory

FACTORY = randog.factory.randstr(
    length=4,
    # Get the value specified for charset from an environment variable
    charset=os.environ["CHARSET"],
)

Logging

By default, all logs are ignored, including those by randog (exceptions are noted below), but can be configured to output log.

Warning

This is an experimental feature. It may be removed or significantly changed in the future.

For log output, you can use one of the following options:

  • --log-stderr <LEVEL>:

    Outputs logs of the specified level or higher to standard error output. The default setting is to omit traceback, but adding “-full” to end of a level, such as --log-stderr ERROR-full, will also output a traceback, such as when an exception occurs.

  • --log <LOGGING_CONFIG_PATH>:

    Uses the specified log configuration file. The file must be in JSON or YAML format and must adhere to configuration dictionary schema. Unlike --log-stderr, traceback is not omitted.

Warning

To use YAML format configuration files, PyYAML must be installed.

In writing the configuration file, you may need information on the loggers used by randog. If so, please refer to Logging, which describes logging without limiting it to command execution.

Note

Warnings are set up through a different mechanism than logging. See also Warning.

Note

In fact, error messages during command execution also use logging. You can override the error message output setting during command execution by specifying disable_existing_loggers: true in the log configuration file. (Although the default value of disable_existing_loggers is true in the standard library specification, the standard error output setting for randog command execution is only overridden if disable_existing_loggers is explicitly set to true.)

Warning

This means that if you specify disable_existing_loggers: true, error messages may not be displayed on abnormal termination, depending on the setting.

Warning

By default, warnings are output to standard error output, but it can be configured.

Warning

This is an experimental feature. It may be removed or significantly changed in the future.

You can hide warnings of randog by using the option --quiet/-q. If you wish to hide all warnings, use python’s -W option; See also here.

Note

It should be possible to hide only randog warnings with -W in the spec, but there seems to be a problem. Use --quiet/-q of randog.

Incidentally, the category of warnings that randog command execution produces is randog.RandogCmdWarning.