[GitHub] [qpid-proton] kpvdr opened a new pull request #192: ENTMQCL-1361: Changed Python API to better handle strings where symbo…

[GitBox <gi...@apache.org>]

kpvdr opened a new pull request #192: ENTMQCL-1361: Changed Python API to better handle strings where symbo…
URL: https://github.com/apache/qpid-proton/pull/192
 
 
   Exception characteristics for API symbol changes
   ================================================
   
   * Old behavior is not changed. If the old API accepted non-symbol or non-string
     keys and/or values, so will the updated API.
   
   * Strings are silently converted to symbols. Where the old API accepted strings, the
     new API will convert them to symbol objects.
   
   * Three new classes have been added to _data:
     * AnnotationDict, which accepts only symbol and ulong keys. However, if string keys
       are provided, they will be converted to symbols.
     * PropertyDict, which accepts only symbol keys. However, if string keys are provided,
       they will be converted to symbols.
     * SymbolList, which accepts only symbol elements. However, if string elements are
       provided, they will be converted to symbols.
   
   * These three classes by default raise exceptions for non-allowed types:
     AnnotationDict: KeyError
     PropertyDict: KeyError
     SymbolList: TypeError
     However, each of these may be forced to accept non-allowed types by using the
     throw=False keyword arg in the constructor of each of these types.
   
   * The idea is to encourage the use of these types for all places in the API where
     restricted key or list types are required by the AMQP specification:
   
     API property  |  Recommended class |  Allowed type(s)
     ------------------|------------------------------|---------------------------
     Message.annotations  |              AnnotationDict |    symbol, string(*), ulong
     Connection.offered_capabilities |   SymbolList   |      symbol, string(*)
     Connection.desired_capabilities |   SymbolList  |       symbol, string(*)
     Connection.properties    |          PropertyDict   |    symbol, string(*)
   
     (*) will be converted into a symbol
   
     By default, they will enforce the correct type, and will raise an error if a
     non-allowed type is used on construction.
   
   Example:
   ```
   >>> from proton import symbol, Array, SymbolList
   >>> from proton.reactor import Container
   >>> from proton.handlers import MessagingHandler
   >>> h = MessagingHandler()
   >>> c = Container(h)
   ```
   By default, non-allowed types are ignored, but strings are converted to symbols:
   ```
   >>> c.connect(offered_capabilities=['one', symbol('two'), 3]).offered_capabilities
   SymbolList([symbol('one'), symbol('two'), 3])
   ```
   but by using a SymbolList object as the value, the default behavior will be to
   enforce non-allowed types:
   ```
   >>> c.connect(offered_capabilities=SymbolList(['one', symbol('two'), 3])).offered_capabilities
      ...
   TypeError: Non-symbol type <class 'int'>: 3
   ```
   Also, previously used patterns are still supported:
   ```
   >>> c.connect(offered_capabilities=Array(UNDESCRIBED, Data.SYMBOL, symbol('one'), symbol('two'))).offered_capabilities
   Array(UNDESCRIBED, 21, symbol('one'), symbol('two'))
   ```

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
For additional commands, e-mail: dev-help@qpid.apache.org