Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document codecs.encode and codecs.decode #62027

Closed
ncoghlan opened this issue Apr 24, 2013 · 13 comments
Closed

Document codecs.encode and codecs.decode #62027

ncoghlan opened this issue Apr 24, 2013 · 13 comments
Labels
docs Documentation in the Doc dir easy type-feature A feature request or enhancement

Comments

@ncoghlan
Copy link
Contributor

BPO 17827
Nosy @warsaw, @ncoghlan, @ezio-melotti, @florentx
Files
  • 17827.diff: 17827-3.4
  • issue17827_docs_py27.diff: Docs patch for Python 2.7
  • Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = None
    closed_at = <Date 2013-11-04.10:08:46.518>
    created_at = <Date 2013-04-24.13:45:40.059>
    labels = ['easy', 'type-feature', 'docs']
    title = 'Document codecs.encode and codecs.decode'
    updated_at = <Date 2013-11-04.10:08:46.517>
    user = 'https://github.com/ncoghlan'

    bugs.python.org fields:

    activity = <Date 2013-11-04.10:08:46.517>
    actor = 'python-dev'
    assignee = 'docs@python'
    closed = True
    closed_date = <Date 2013-11-04.10:08:46.518>
    closer = 'python-dev'
    components = ['Documentation']
    creation = <Date 2013-04-24.13:45:40.059>
    creator = 'ncoghlan'
    dependencies = []
    files = ['30860', '32492']
    hgrepos = []
    issue_num = 17827
    keywords = ['patch', 'easy']
    message_count = 13.0
    messages = ['187700', '187765', '187866', '187867', '187871', '187910', '192625', '198848', '199713', '199718', '202099', '202101', '202108']
    nosy_count = 8.0
    nosy_names = ['barry', 'ncoghlan', 'ezio.melotti', 'flox', 'docs@python', 'tshepang', 'python-dev', 'Grant']
    pr_nums = []
    priority = 'normal'
    resolution = 'fixed'
    stage = 'resolved'
    status = 'closed'
    superseder = None
    type = 'enhancement'
    url = 'https://bugs.python.org/issue17827'
    versions = ['Python 2.7']

    @ncoghlan
    Copy link
    Contributor Author

    The codecs module has long offered encode() and decode() convenience functions (since 2004: http://hg.python.org/cpython-fullhistory/rev/8ea2cb1ec598), but they're not documented (except through docstrings). We should fix that.

    From the docstrings:
    ==========
    encode(obj, [encoding[,errors]]) -> object

    Encodes obj using the codec registered for encoding. encoding defaults
    to the default encoding. errors may be given to set a different error
    handling scheme. Default is 'strict' meaning that encoding errors raise
    a ValueError. Other possible values are 'ignore', 'replace' and
    'xmlcharrefreplace' as well as any other name registered with
    codecs.register_error that can handle ValueErrors.
    ==========
    decode(obj, [encoding[,errors]]) -> object

    Decodes obj using the codec registered for encoding. encoding defaults
    to the default encoding. errors may be given to set a different error
    handling scheme. Default is 'strict' meaning that encoding errors raise
    a ValueError. Other possible values are 'ignore' and 'replace'
    as well as any other name registered with codecs.register_error that is
    able to handle ValueErrors.
    ==========

    Note that the difference between the convenience functions in the codecs module and the methods on str, bytes and bytearray is that the latter have additional type checks to limit their usage to text encodings. str.encode expects a str->bytes conversion, while bytes.decode and bytearray.decode both expect the codec to produce a str object. codecs.encode and codecs.decode are both arbitrary object->object conversions, limited only by whatever the chosen codec supports.

    @ncoghlan ncoghlan added the docs Documentation in the Doc dir label Apr 24, 2013
    @ezio-melotti ezio-melotti added easy type-feature A feature request or enhancement labels Apr 24, 2013
    @ncoghlan
    Copy link
    Contributor Author

    Note that in 2.7, these docs should have a ":versionadded: 2.4" marker, while in 3.3 and 3.4, they shouldn't have a version added marker at all.

    These functions should also get an entry in the 3.4 What's New, even though they're not actually new.

    @tshepang
    Copy link
    Mannequin

    tshepang mannequin commented Apr 26, 2013

    So, why place them in What's New?

    @ezio-melotti
    Copy link
    Member

    To advertise them? It should be explained that they are not new, but that now they are documented and can/should be used.

    @tshepang
    Copy link
    Mannequin

    tshepang mannequin commented Apr 26, 2013

    I was not aware that such things are placed in What's New. I just looked at such a document for 3.3... makes a lot of sense.

    @ncoghlan
    Copy link
    Contributor Author

    This is only the second case I'm aware of where a particularly interesting piece of functionality didn't get mentioned in the appropriate What's New doc. For the other case, the zipfile execution support, we just added it in to the 2.6 What's New long after 2.6 had been released. To this day, most people don't know about that capability, which is why I suggest it's worth handling the current case (codecs.encode and codecs.decode) differently and noting their existence in the next What's New doc that people are likely to read :)

    @Grant
    Copy link
    Mannequin

    Grant mannequin commented Jul 8, 2013

    codecs module and 'whats new' doc patch for 3.4

    @ncoghlan
    Copy link
    Contributor Author

    ncoghlan commented Oct 2, 2013

    We should fix the docs for the earlier versions as well.

    @python-dev
    Copy link
    Mannequin

    python-dev mannequin commented Oct 13, 2013

    New changeset b607ce6c9ee6 by Nick Coghlan in branch '3.3':
    Issue bpo-17827: Document codecs.encode and codecs.decode
    http://hg.python.org/cpython/rev/b607ce6c9ee6

    New changeset 32f3d6721c84 by Nick Coghlan in branch 'default':
    Issue bpo-17827: document codecs.encode and codecs.decode
    http://hg.python.org/cpython/rev/32f3d6721c84

    @ncoghlan
    Copy link
    Contributor Author

    Still need to backport this to 2.7

    (Thanks for the preliminary patch Grant, but I'm afraid it didn't make it into what I ended up committing)

    @ncoghlan
    Copy link
    Contributor Author

    ncoghlan commented Nov 4, 2013

    Hmm, I just noticed an interesting issue here in drafting the 2.7 backport: as near as I can tell, these aren't tested, so other implementations that failed to provide them would pass the 2.7 and 3.3 test suites.

    @ncoghlan ncoghlan changed the title Document codecs.encode and codecs.decode Document and test codecs.encode and codecs.decode Nov 4, 2013
    @ncoghlan
    Copy link
    Contributor Author

    ncoghlan commented Nov 4, 2013

    Oops, never mind - the tests are already there (and have been since MAL's original commit prior to Python 2.4), I just fail at searching code.

    @ncoghlan ncoghlan changed the title Document and test codecs.encode and codecs.decode Document codecs.encode and codecs.decode Nov 4, 2013
    @python-dev
    Copy link
    Mannequin

    python-dev mannequin commented Nov 4, 2013

    New changeset bdb30bdf60a5 by Nick Coghlan in branch '2.7':
    Close bpo-17827: Document codecs.encode & codecs.decode
    http://hg.python.org/cpython/rev/bdb30bdf60a5

    @python-dev python-dev mannequin closed this as completed Nov 4, 2013
    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    docs Documentation in the Doc dir easy type-feature A feature request or enhancement
    Projects
    None yet
    Development

    No branches or pull requests

    2 participants