Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/tables/parameters.py: 100%
49 statements
« prev ^ index » next coverage.py v7.2.5, created at 2023-05-10 06:15 +0000
1"""Parameters for PyTables."""
3import os as _os
6__docformat__ = 'reStructuredText'
7"""The format of documentation strings in this module."""
9_KB = 1024
10"""The size of a Kilobyte in bytes"""
12_MB = 1024 * _KB
13"""The size of a Megabyte in bytes"""
15# Tunable parameters
16# ==================
17# Be careful when touching these!
19# Parameters for different internal caches
20# ----------------------------------------
22BOUNDS_MAX_SIZE = 1 * _MB
23"""The maximum size for bounds values cached during index lookups."""
25BOUNDS_MAX_SLOTS = 4 * _KB
26"""The maximum number of slots for the BOUNDS cache."""
28ITERSEQ_MAX_ELEMENTS = 1 * _KB
29"""The maximum number of iterator elements cached in data lookups."""
31ITERSEQ_MAX_SIZE = 1 * _MB
32"""The maximum space that will take ITERSEQ cache (in bytes)."""
34ITERSEQ_MAX_SLOTS = 128
35"""The maximum number of slots in ITERSEQ cache."""
37LIMBOUNDS_MAX_SIZE = 256 * _KB
38"""The maximum size for the query limits (for example, ``(lim1, lim2)``
39in conditions like ``lim1 <= col < lim2``) cached during index lookups
40(in bytes)."""
42LIMBOUNDS_MAX_SLOTS = 128
43"""The maximum number of slots for LIMBOUNDS cache."""
45TABLE_MAX_SIZE = 1 * _MB
46"""The maximum size for table chunks cached during index queries."""
48SORTED_MAX_SIZE = 1 * _MB
49"""The maximum size for sorted values cached during index lookups."""
51SORTEDLR_MAX_SIZE = 8 * _MB
52"""The maximum size for chunks in last row cached in index lookups (in
53bytes)."""
55SORTEDLR_MAX_SLOTS = 1 * _KB
56"""The maximum number of chunks for SORTEDLR cache."""
59# Parameters for general cache behaviour
60# --------------------------------------
61#
62# The next parameters will not be effective if passed to the
63# `open_file()` function (so, they can only be changed in a *global*
64# way). You can change them in the file, but this is strongly
65# discouraged unless you know well what you are doing.
67DISABLE_EVERY_CYCLES = 10
68"""The number of cycles in which a cache will be forced to be disabled
69if the hit ratio is lower than the LOWEST_HIT_RATIO (see below). This
70value should provide time enough to check whether the cache is being
71efficient or not."""
73ENABLE_EVERY_CYCLES = 50
74"""The number of cycles in which a cache will be forced to be
75(re-)enabled, irregardingly of the hit ratio. This will provide a chance
76for checking if we are in a better scenario for doing caching again."""
78LOWEST_HIT_RATIO = 0.6
79"""The minimum acceptable hit ratio for a cache to avoid disabling (and
80freeing) it."""
83# Tunable parameters
84# ==================
85# Be careful when touching these!
87# Recommended maximum values
88# --------------------------
90# Following are the recommended values for several limits. However,
91# these limits are somewhat arbitrary and can be increased if you have
92# enough resources.
94MAX_COLUMNS = 512
95"""Maximum number of columns in :class:`tables.Table` objects before a
96:exc:`tables.PerformanceWarning` is issued. This limit is somewhat
97arbitrary and can be increased.
98"""
100MAX_NODE_ATTRS = 4 * _KB
101"""Maximum allowed number of attributes in a node."""
103MAX_GROUP_WIDTH = 16 * _KB
104"""Maximum allowed number of children hanging from a group."""
106MAX_TREE_DEPTH = 2 * _KB
107"""Maximum depth in object tree allowed."""
109MAX_UNDO_PATH_LENGTH = 10 * _KB
110"""Maximum length of paths allowed in undo/redo operations."""
113# Cache limits
114# ------------
116COND_CACHE_SLOTS = 128
117"""Maximum number of conditions for table queries to be kept in memory."""
119CHUNK_CACHE_NELMTS = 521
120"""Number of elements for HDF5 chunk cache."""
122CHUNK_CACHE_PREEMPT = 0.0
123"""Chunk preemption policy. This value should be between 0 and 1
124inclusive and indicates how much chunks that have been fully read are
125favored for preemption. A value of zero means fully read chunks are
126treated no differently than other chunks (the preemption is strictly
127LRU) while a value of one means fully read chunks are always preempted
128before other chunks."""
130CHUNK_CACHE_SIZE = 16 * _MB
131"""Size (in bytes) for HDF5 chunk cache."""
133# Size for new metadata cache system
134METADATA_CACHE_SIZE = 1 * _MB # 1 MB is the default for HDF5
135"""Size (in bytes) of the HDF5 metadata cache."""
138# NODE_CACHE_SLOTS tells the number of nodes that fits in the cache.
139#
140# There are several forces driving the election of this number:
141# 1.- As more nodes, better chances to re-use nodes
142# --> better performance
143# 2.- As more nodes, the re-ordering of the LRU cache takes more time
144# --> less performance
145# 3.- As more nodes, the memory needs for PyTables grows, specially for table
146# writings (that could take double of memory than table reads!).
147#
148# The default value here is quite conservative. If you have a system
149# with tons of memory, and if you are touching regularly a very large
150# number of leaves, try increasing this value and see if it fits better
151# for you. Please report back your feedback.
152# Using a lower value than 64 provides a workaround for issue #977.
153NODE_CACHE_SLOTS = 32
154"""Maximum number of nodes to be kept in the metadata cache.
156It is the number of nodes to be kept in the metadata cache. Least recently
157used nodes are unloaded from memory when this number of loaded nodes is
158reached. To load a node again, simply access it as usual.
159Nodes referenced by user variables and, in general, all nodes that are still
160open are registered in the node manager and can be quickly accessed even
161if they are not in the cache.
163Negative value means that all the touched nodes will be kept in an
164internal dictionary. This is the faster way to load/retrieve nodes.
165However, and in order to avoid a large memory comsumption, the user will
166be warned when the number of loaded nodes will reach the
167``-NODE_CACHE_SLOTS`` value.
169Finally, a value of zero means that any cache mechanism is disabled.
170"""
173# Parameters for the I/O buffer in `Leaf` objects
174# -----------------------------------------------
176IO_BUFFER_SIZE = 16 * _MB
177"""The PyTables internal buffer size for I/O purposes. Should not
178exceed the amount of highest level cache size in your CPU."""
180BUFFER_TIMES = 100
181"""The maximum buffersize/rowsize ratio before issuing a
182:exc:`tables.PerformanceWarning`."""
185# Miscellaneous
186# -------------
188EXPECTED_ROWS_EARRAY = 1000
189"""Default expected number of rows for :class:`EArray` objects."""
191EXPECTED_ROWS_VLARRAY = 1000
192"""Default expected number of rows for :class:`VLArray` objects.
194.. versionadded:: 3.0
196"""
198EXPECTED_ROWS_TABLE = 10_000
199"""Default expected number of rows for :class:`Table` objects."""
201PYTABLES_SYS_ATTRS = True
202"""Set this to ``False`` if you don't want to create PyTables system
203attributes in datasets. Also, if set to ``False`` the possible existing
204system attributes are not considered for guessing the class of the node
205during its loading from disk (this work is delegated to the PyTables'
206class discoverer function for general HDF5 files)."""
208MAX_NUMEXPR_THREADS = int(_os.environ.get("NUMEXPR_MAX_THREADS", 4))
209"""The maximum number of threads that PyTables should use internally in
210Numexpr. If `None`, it is automatically set to the number of cores in
211your machine. In general, it is a good idea to set this to the number of
212cores in your machine or, when your machine has many of them (e.g. > 8),
213perhaps stay at 8 at maximum. In general, 4 threads is a good tradeoff."""
215MAX_BLOSC_THREADS = 1 # 1 is safe for concurrency
216"""The maximum number of threads that PyTables should use internally in
217Blosc. If `None`, it is automatically set to the number of cores in
218your machine. For applications that use several PyTables instances
219concurrently and so as to avoid locking problems, the recommended value
220is 1. In other cases a value of 2 or 4 could make sense.
222"""
224USER_BLOCK_SIZE = 0
225"""Sets the user block size of a file.
227The default user block size is 0; it may be set to any power of 2 equal
228to 512 or greater (512, 1024, 2048, etc.).
230.. versionadded:: 3.0
232"""
234ALLOW_PADDING = True
235"""Allow padding in compound data types.
237Starting on version 3.5 padding is honored during copies, or when tables
238are created from NumPy structured arrays with padding (e.g. `align=True`).
239If you actually want to get rid of any possible padding in new
240datasets/attributes (i.e. the previous behaviour), set this to `False`.
242.. versionadded:: 3.5
244"""
247# HDF5 driver management
248# ----------------------
249DRIVER = None
250"""The HDF5 driver that should be used for reading/writing to the file.
252Following drivers are supported:
254 * H5FD_SEC2: this driver uses POSIX file-system functions like read
255 and write to perform I/O to a single, permanent file on local
256 disk with no system buffering.
257 This driver is POSIX-compliant and is the default file driver for
258 all systems.
260 * H5FD_DIRECT: this is the H5FD_SEC2 driver except data is written
261 to or read from the file synchronously without being cached by
262 the system.
264 * H5FD_WINDOWS: this driver was modified in HDF5-1.8.8 to be a
265 wrapper of the POSIX driver, H5FD_SEC2. This change should not
266 affect user applications.
268 * H5FD_STDIO: this driver uses functions from the standard C
269 stdio.h to perform I/O to a single, permanent file on local disk
270 with additional system buffering.
272 * H5FD_CORE: with this driver, an application can work with a file
273 in memory for faster reads and writes. File contents are kept in
274 memory until the file is closed. At closing, the memory version
275 of the file can be written back to disk or abandoned.
277 * H5FD_SPLIT: this file driver splits a file into two parts.
278 One part stores metadata, and the other part stores raw data.
279 This splitting a file into two parts is a limited case of the
280 Multi driver.
282The following drivers are not currently supported:
284 * H5FD_LOG: this is the H5FD_SEC2 driver with logging capabilities.
286 * H5FD_FAMILY: with this driver, the HDF5 file’s address space is
287 partitioned into pieces and sent to separate storage files using
288 an underlying driver of the user’s choice.
289 This driver is for systems that do not support files larger than
290 2 gigabytes.
292 * H5FD_MULTI: with this driver, data can be stored in multiple
293 files according to the type of the data. I/O might work better if
294 data is stored in separate files based on the type of data.
295 The Split driver is a special case of this driver.
297 * H5FD_MPIO: this is the standard HDF5 file driver for parallel
298 file systems. This driver uses the MPI standard for both
299 communication and file I/O.
301 * H5FD_MPIPOSIX: this parallel file system driver uses MPI for
302 communication and POSIX file-system calls for file I/O.
304 * H5FD_STREAM: this driver is no longer available.
306.. seealso:: the `Drivers section`_ of the `HDF5 User's Guide`_ for
307 more information.
309.. note::
311 not all supported drivers are always available. For example the
312 H5FD_WINDOWS driver is not available on non Windows platforms.
314 If the user try to use a driver that is not available on the target
315 platform a :exc:`RuntimeError` is raised.
317.. versionadded:: 3.0
319.. _`Drivers section`:
320 http://www.hdfgroup.org/HDF5/doc/UG/08_TheFile.html#Drivers
321.. _`HDF5 User's Guide`: http://www.hdfgroup.org/HDF5/doc/UG/index.html
323"""
325DRIVER_DIRECT_ALIGNMENT = 0
326"""Specifies the required alignment boundary in memory.
328A value of 0 (zero) means to use HDF5 Library’s default value.
330.. versionadded:: 3.0
332"""
334DRIVER_DIRECT_BLOCK_SIZE = 0
335"""Specifies the file system block size.
337A value of 0 (zero) means to use HDF5 Library’s default value of 4KB.
339.. versionadded:: 3.0
341"""
343DRIVER_DIRECT_CBUF_SIZE = 0
344"""Specifies the copy buffer size.
346A value of 0 (zero) means to use HDF5 Library’s default value.
348.. versionadded:: 3.0
350"""
352# DRIVER_LOG_FLAGS = 0x0001ffff
353# """Flags specifying the types of logging activity.
354#
355# .. versionadded:: 3.0
356#
357# .. seeealso::
358# http://www.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-SetFaplLog
359#
360# """
361#
362# DRIVER_LOG_BUF_SIZE = 4 * _KB
363# """The size of the logging buffers, in bytes.
364#
365# One buffer of size DRIVER_LOG_BUF_SIZE will be created for each of
366# H5FD_LOG_FILE_READ, H5FD_LOG_FILE_WRITE and H5FD_LOG_FLAVOR when those
367# flags are set; these buffers will not grow as the file increases in
368# size.
369#
370# .. versionadded:: 3.0
371#
372# """
374DRIVER_CORE_INCREMENT = 64 * _KB
375"""Core driver memory increment.
377Specifies the increment by which allocated memory is to be increased
378each time more memory is required.
380.. versionadded:: 3.0
382"""
384DRIVER_CORE_BACKING_STORE = 1
385"""Enables backing store for the core driver.
387With the H5FD_CORE driver, if the DRIVER_CORE_BACKING_STORE is set
388to 1 (True), the file contents are flushed to a file with the same name
389as this core file when the file is closed or access to the file is
390terminated in memory.
392The application is allowed to open an existing file with H5FD_CORE
393driver. In that case, if the DRIVER_CORE_BACKING_STORE is set to 1 and
394the flags for :func:`tables.open_file` is set to H5F_ACC_RDWR, any change
395to the file contents are saved to the file when the file is closed.
396If backing_store is set to 0 and the flags for :func:`tables.open_file`
397is set to H5F_ACC_RDWR, any change to the file contents will be lost
398when the file is closed. If the flags for :func:`tables.open_file` is
399set to H5F_ACC_RDONLY, no change to the file is allowed either in
400memory or on file.
402.. versionadded:: 3.0
404"""
406DRIVER_CORE_IMAGE = None
407"""String containing an HDF5 file image.
409If this option is passed to the :func:`tables.open_file` function then the
410returned file object is set up using the specified image.
412A file image can be retrieved from an existing (and opened) file object
413using the :meth:`tables.File.get_file_image` method.
415.. note:: requires HDF5 >= 1.8.9.
417.. versionadded:: 3.0
419"""
421DRIVER_SPLIT_META_EXT = '-m.h5'
422"""The extension for the metadata file used by the H5FD_SPLIT driver.
424If this option is passed to the :func:`tables.openFile` function along
425with driver='H5FD_SPLIT', the extension is appended to the name passed
426as the first parameter to form the name of the metadata file. If the
427string '%s' is used in the extension, the metadata file name is formed
428by replacing '%s' with the name passed as the first parameter instead.
430.. versionadded:: 3.1
432"""
434DRIVER_SPLIT_RAW_EXT = '-r.h5'
435"""The extension for the raw data file used by the H5FD_SPLIT driver.
437If this option is passed to the :func:`tables.openFile` function along
438with driver='H5FD_SPLIT', the extension is appended to the name passed
439as the first parameter to form the name of the raw data file. If the
440string '%s' is used in the extension, the raw data file name is formed
441by replacing '%s' with the name passed as the first parameter instead.
443.. versionadded:: 3.1
445"""