bitformat replacing bitstring functionality?

[scott-griffiths]

There's a temptation to make bitformat a bit of a re-write of bitstring in terms of the user interface. A lot of the design choices in bitstring were taken over 15 years ago, with Python 2.4 in mind. I'd make quite a few different choices if designing it now.

This doesn't need to be a great deal of work, as for now at least there's no need to rewrite the functionality, I can just make a new API that calls the bitstring methods. Later it might need reworking for efficiency of course.

These are just suggestions so that they can be thought about, but need to get something done in writing first:

New class BitField. Perhaps this has a better name later, but I don't want to call it Bits as that would be confusing. It is however basically a replacement for bitstring.Bits.

BitField

• Immutable.
• No properties. Instead of s.bin use s.to('bin'), or to some Dtype.
• Instead of mutating methods have methods that return a new BitField.
• No streaming functionality. We can later add this, but I wouldn't derive a new class from BitField, instead just make a class that has BitField and a pos members.

Methods

Included the same as bitstring.Bits:

• all
• any
• count
• cut
• endswith
• find
• findall
• join
• pp
• rfind
• startswith

Not included:

• copy [unneeded as immutable]
• frombytes [suggest .from('bytes', b) instead, see below]
• fromstring [suggest .from('str', s) instead, see below]
• split [Not sure if it's useful]
• tobitarray
• tobytes [suggest that this is just .to('bytes'), see below]
• tofile [Want to avoid file issues]
• unpack [Covered elsewhere in bitformat]

Special methods

Probably include the same as bitstring.Bits (?)

Methods from bitstring.BitArray:

These all need new signatures to return a BitField:

• append
• byteswap
• insert
• invert [? is it useful enough]
• overwrite
• prepend
• replace
• reverse
• set

Not included:

• clear [no point]
• all special methods

New methods

BitField.to(t: str | Dtype, /) -> Any

This replaces tobytes() with to('bytes') and also allows to('bin') etc. to replace the getter properties.

BitField.from(t: str | Dtype, value: Any, /) -> BitField

Creates new BitField to replace the setter properties. Possibly don't allow the t to be a value such as u12=4 and instead require it to only specify the type. This makes the interface clearer. You can now also do x = BitField.from('bytes', b) which makes x = BitField.frombytes(b) a bit redundant. Also I think I like x = BitField.from('str', s) instead of x = BitField.fromstring(s).

MVP

• __getitem__ (Note: do we want to return a BitField or a bool for a single item)
• to()
• from()
• append()

That's a shorter list than I expected!

Other stuff

• The .from('str', s) would be using the new bitformat strings. So disallow things like the '*' multiplier etc.
• The from and to methods could accept array formats. So x = BitField.from('[bool; 3]', [True, False, False]) or b.to('[u8;5]'). This could be quite cool. Also b.to('[u8]') without a length would be useful.

Could this replace all the bitstring.Array functionality? No, as the BitField doesn't know its Dtype. But a lot could still be done. And a BitField + Dtype can do just about everything.

These two I think are equivalent:
bitfield.to(dtype) -> Any
dtype.parse(bitfield) -> Any

As are these:
BitField.from(dtype, value) -> BitField
dtype.build(value) -> BitField

I think they're both reasonable to have, but they can essentially share one implementation.

[scott-griffiths]

Unfortunately from is a reserved keyword (forgot that!)

Would it be crazy to use parse and build instead of to and from?

x = BitField.build('bytes', b)
y = BitField.build('hex', '0xabc')

bitfield.parse(dtype) -> Any
dtype.parse(bitfield) -> Any

BitField.build(dtype, value) -> BitField
dtype.build(value) -> BitField

I'm tempted to keep BitField.fromstring(s) though. If only because str isn't a valid Dtype, so it would have to be a special case.