Metadata-Version: 1.1
Name: bitflags
Version: 1.0.3
Summary: Bit flags implementation using a C Union. This library removes the need to use ctypes and helps you quickly access what bits are toggled.
Home-page: https://github.com/justengel/bitflags
Author: Justin Engel
Author-email: jtengel08@gmail.com
License: MIT
Download-URL: https://github.com/justengel/bitflags/archive/v1.0.3.tar.gz
Description: # bitflags
        Bit flags implementation using a C Union. This library removes the need to use ctypes and helps you quickly access what 
        bits are toggled.
        
        This class is built off of the Bit Manipulation guide found at https://wiki.python.org/moin/BitManipulation under the 
        Bit fields section.
        
        This library includes a class based approach to bit flags (BitFlags) and a one time dynamic bit flags object (bitflags).
        
        The individual bits can always be accessed with 'flag.bit_0', 'flag.bit_1', 'flag.bit_2', ...
        
        ## Example - BitFlags
        This is the class based approach.
        
        ```python
        from bitflags import BitFlags
        
        
        class MyFlags(BitFlags):
            options = {0: "flag1", 1: "flag2", 2: "flag3", 3: "flag4", 4: "Something Happened"}
            
            
        f = MyFlags(0)
        
        assert f.value == 0
        assert int(f) == 0
        
        f.value = 0b101  # 5 - bin(5) shows the bit values (0b101)
        assert f.value == 0b101
        
        # You can always access the bit value with 'bit_X'
        # Access all of the bits (The number of bits can be changed by setting the class attribute nbits or nbytes
        print(f.bit_7, f.bit_6, f.bit_5, f.bit_4, f.bit_3, f.bit_2, f.bit_1, f.bit_0)
        # 0 0 0 0 0 1 0 1
        
        # Access the custom flags as attributes
        assert f.flag1 == 1
        assert f.flag2 == 0
        assert f.flag3 == 1
        assert f.flag4 == 0
        assert f.something_happened == 0
        
        # Get a list of flag options
        assert f.get_flags() == ['flag1', 'flag3']
        
        # Convert to use the data types
        assert str(f) == 'flag1, flag3'
        assert int(f) == 5
        assert bytes(f) == b'\x05'
        ```
        
        This class was made to be flexible if you want the attributes to be different from the display options.
        
         ```python
        from bitflags import BitFlags
        
        
        class MyFlags(BitFlags):
            options = {0: "Failure", 1: "Warning", 2: "System 2% Overloaded"}
            
        f = MyFlags(0b111)
        assert hasattr(f, 'failure')
        assert hasattr(f, 'warning')
        assert hasattr(f, 'system_2_overloaded')
        
        assert f.get_flags() == ['Failure', 'Warning', 'System 2% Overloaded']
        
        
        class SpecialFlags(BitFlags):
            options = {0: "2% System Failure",  # Note: variable name cannot start with a number!
                       1: "System Overloaded",
                       2: "System Safe"}
            fields = {'system_failure': 0, 'system_overload': 1, 'safe': 2}  # Custom variables to access the bits
            
        s = SpecialFlags(7)
        
        assert s.system_failure == 1
        assert s.system_overload == 1
        assert s.safe == 1
        
        assert s.get_flags() == ["2% System Failure", "System Overloaded", "System Safe"]
        
        
        s2 = SpecialFlags(1)
        assert s.get_flags() == ["2% System Failure"]
        ```
        
        You can also make a pattern for options.
        
        ```python
        from bitflags import BitFlags
        
        
        class MyFlags(BitFlags):
            pattern = '%i'
        
        f = MyFlags()
        f.value = 0b101  # 5 - bin(5) shows the bit values (0b101)
        assert f.value == 0b101
        
        # Get a list of flag options
        assert f.get_flags() == ['0', '2']
        
        # Convert to use the data types
        assert str(f) == '0, 2'
        assert int(f) == 5
        assert bytes(f) == b'\x05'
        ```
        
        
        ## Example - bitflags
        The one time object bit flags. This is basically the same thing as BitFlags only the instance constructor allows you 
        to set the options, fields, and number of bits/bytes.
        
        ```python
        from bitflags import bitflags
        
        f = bitflags(flag1=1, flag3=1, options={0: "flag1", 1: "flag2", 2: "flag3", 3: "flag4", 4: "Something Happened"})
        
        assert f.value == 0b101
        
        assert f.flag1 == 1
        assert f.flag2 == 0
        assert f.flag3 == 1
        assert f.flag4 == 0
        assert f.something_happened == 0
        
        # Change the fields that access the bits.
        f.set_fields({'a': 0, 'b': 1, 'c': 2, 'd': 3})
        
        assert f.a == f.bit_0
        assert f.b == f.bit_1
        assert f.c == f.bit_2
        assert f.d == f.bit_3
        ```
        
        The bitflags constructor uses type to create a new BitFlags class. This class isn't really re-usable unless you access 
        that class from the object that was created.
        
        ```python
        from bitflags import bitflags
        
        f = bitflags(flag1=1, flag3=1, options={0: "flag1", 1: "flag2", 2: "flag3", 3: "flag4", 4: "Something Happened"})
        
        assert f.value == 0b101
        
        f2 = type(f)(0b1)
        assert f2.flag1 == 1
        assert f2.value == 1
        assert f.value == 0b101
        
        f3 = f.__class__(0b10)
        assert f3.flag1 == 0
        assert f3.flag2 == 1
        assert f3.value == 2
        assert f2.value == 1
        assert f.value == 0b101
        ```
        
        If you want to use multiple bit flag objects that have the same fields then it is better to use BitFlags class 
        inheritance.
        
Keywords: bit,flags,Union,bitflags
Platform: any
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
