libgit2 / libgit2/pygit2

Consistent interface to get text and bytes

Open
#895 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
1.7k
Forks
408
Avg merge
2d 57m
Merged PRs (30d)
7

Description

Follow up from #610 #790 and #893

General policy:

  • Do not implement str()
  • To get unicode string use .text
  • In .text use UTF-8 and replace (the rationale for replace is explained in https://github.com/libgit2/pygit2/pull/790#issuecomment-385906316)
  • To get the byte string use .data or .raw (this is to be decided)
  • For attributes the name of the attribute returns text, prefix with raw_ to get bytes. For instance Signature.name and Signature.raw_name
  • Implement the buffer protocol, bytes(..) where appropriate

Open for discussion.

TODO:

  • Replace TreeEntry._name by .raw_name
  • Replace DiffLine.content by .text
  • Inventory all the places where we get bytes, text, or the buffer protocol
  • Settle on .data or .raw
  • Replace DiffLine.raw_content by .data or .raw
  • Replace Object.read_raw() by .data (or .raw), then remove Blob.data (it will inherit from Object)
  • Settle on str() bytes() and the buffer protocol

The case of Oid, what we've now:

  • oid.raw returns the byte string (that's good, unless we decide to settle on .data)
  • str(oid) and oid.hex both return the hex representation, always <str> (bytes in Python 2 and text in Python 3)
  • Oid is the only place where we implement str(...)
  • Object.hex and TreeEntry.hex behave the same, they return always <str>. Apparently these are the only places where we always return <str>.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the linked issues #610, #790, and #893, then inventory the current Oid, Object, TreeEntry, and DiffLine interfaces described here. Done requires settling the text/bytes naming and conversion policy and resolving the listed TODOs consistently across the bindings.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, python
Domain
api, backend-api-design, tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.