আমি আমার পাইথন মডিউলগুলির জন্য API ডকুমেন্টেশন জেনার জন্য স্ফিংস এবং অটোডোক প্লাগইন ব্যবহার করছি । সুনির্দিষ্টভাবে নির্দিষ্ট পরামিতিগুলি কীভাবে ডকুমেন্ট করা যায় তা আমি দেখতে পেলাম, প্যারামিটারটি কীভাবে ডকুমেন্ট করব তার উদাহরণ আমি পাই না **kwargs।
এগুলি নথিভুক্ত করার সুস্পষ্ট উপায়ে কারোর কাছে কি উদাহরণ রয়েছে?
উত্তর:
আমি মনে করি subprocess- মডিউল এর ডক্স একটি ভাল উদাহরণ। শীর্ষ / পিতাম শ্রেণীর জন্য সমস্ত পরামিতিগুলির একটি সম্পূর্ণ তালিকা দিন । তারপরে অন্য সমস্ত ঘটনার জন্য কেবল সেই তালিকাটি দেখুন **kwargs।
subprocess.call(*popenargs, **kwargs)। এটি নথিবদ্ধ subprocess.call(args, *, stdin=None, stdout=None, stderr=None, shell=False)যেখানে সমস্ত কিছুর পরে *স্বীকৃত কীগুলি **kwargs(বা কমপক্ষে প্রায়শই ব্যবহৃত হয়)
subprocess.Popenএবং আমি নিশ্চিত নই যে এটির আর কোনও বিশেষ উদাহরণ।
এই প্রশ্নটি সন্ধানের পরে আমি নিম্নলিখিতটিতে স্থির হয়েছি, যা বৈধ স্পিংক্স এবং মোটামুটি ভালভাবে কাজ করে:
def some_function(first, second="two", **kwargs):
r"""Fetches and returns this thing
:param first:
The first parameter
:type first: ``int``
:param second:
The second parameter
:type second: ``str``
:param \**kwargs:
See below
:Keyword Arguments:
* *extra* (``list``) --
Extra stuff
* *supplement* (``dict``) --
Additional content
"""
r"""..."""এই একটি "কাঁচা" docstring করতে এবং এইভাবে রাখা প্রয়োজন বোধ করা হয় \*অক্ষত (স্পিংক্স একটি আক্ষরিক যেমন কুড়ান করার জন্য *এবং "জোর" শুরুর)।
নির্বাচিত ফর্ম্যাটিং (বুলেটযুক্ত তালিকার প্রথম বন্ধনীযুক্ত টাইপ এবং এম-ড্যাশ-বিচ্ছিন্ন বিবরণ সহ) কেবল স্পিনক্সের দ্বারা সরবরাহিত স্বয়ংক্রিয় বিন্যাসের সাথে মেলে।
একবার আপনি "কীওয়ার্ড আর্গুমেন্টস" বিভাগটি ডিফল্ট "পরামিতি" বিভাগের মতো দেখানোর চেষ্টা করে গেলে মনে হয় আপনার নিজের পরামিতি বিভাগটি শুরু থেকেই রোল করা সহজ হতে পারে (অন্যান্য উত্তরগুলির কয়েকটি হিসাবে) , তবে ধারণার প্রমাণ হিসাবে পরিপূরকগুলির জন্য সুন্দর চেহারা অর্জনের এটি একটি উপায় **kwargsযদি আপনি ইতিমধ্যে স্পিনক্স ব্যবহার করছেন।
গুগল স্টাইলের ডক্টরিংগুলি স্পিনক্স পার্স করেছেন
দাবি অস্বীকার: পরীক্ষিত নয়।
এই cutout থেকে স্পিংক্স docstring উদাহরণ , *argsএবং **kwargsফেলে রাখা হয় unexpanded :
def module_level_function(param1, param2=None, *args, **kwargs):
"""
...
Args:
param1 (int): The first parameter.
param2 (Optional[str]): The second parameter. Defaults to None.
Second line of description should be indented.
*args: Variable length argument list.
**kwargs: Arbitrary keyword arguments.
কমপ্যাক্টনেসের জন্য আমি নীচের সমাধানটি প্রস্তাব করব :
"""
Args:
param1 (int): The first parameter.
param2 (Optional[str]): The second parameter. Defaults to None.
Second line of description should be indented.
*param3 (int): description
*param4 (str):
...
**key1 (int): description
**key2 (int): description
...
কিভাবে আর্গুমেন্ট Optionalজন্য প্রয়োজন হয় তা লক্ষ করুন **key।
অন্যথায় , আপনি স্পষ্টভাবে * টির নীচে Other Parametersএবং এর **kwargsনীচে Keyword Args(পার্স করা বিভাগগুলি দেখুন ) তালিকাভুক্ত করতে পারেন :
"""
Args:
param1 (int): The first parameter.
param2 (Optional[str]): The second parameter. Defaults to None.
Second line of description should be indented.
Other Parameters:
param3 (int): description
param4 (str):
...
Keyword Args:
key1 (int): description
key2 (int): description
...
তাদের ডকুমেন্টেশনে স্পিনক্সের জন্য একটি ডক্টস্ট্রিংয়ের উদাহরণ রয়েছে । বিশেষত তারা নিম্নলিখিতটি দেখায়:
def public_fn_with_googley_docstring(name, state=None):
"""This function does something.
Args:
name (str): The name to use.
Kwargs:
state (bool): Current state to be in.
Returns:
int. The return code::
0 -- Success!
1 -- No good.
2 -- Try again.
Raises:
AttributeError, KeyError
A really great idea. A way you might use me is
>>> print public_fn_with_googley_docstring(name='foo', state=None)
0
BTW, this always returns 0. **NEVER** use with :class:`MyPublicClass`.
"""
return 0
যদিও আপনি সম্পর্কে জিজ্ঞাসা স্ফিংক্সস্পষ্টতই, আমি গুগল পাইথন স্টাইল গাইডকেও নির্দেশ করব । তাদের দৃষ্টান্তমূলক উদাহরণ থেকে বোঝা যাচ্ছে যে তারা কাওয়ার্গগুলি বিশেষভাবে ডাকে না। (অন্যান্য_সিলি_চলিত = কিছুই নয়)
def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
"""Fetches rows from a Bigtable.
Retrieves rows pertaining to the given keys from the Table instance
represented by big_table. Silly things may happen if
other_silly_variable is not None.
Args:
big_table: An open Bigtable Table instance.
keys: A sequence of strings representing the key of each table row
to fetch.
other_silly_variable: Another optional variable, that has a much
longer name than the other args, and which does nothing.
Returns:
A dict mapping keys to the corresponding table row data
fetched. Each row is represented as a tuple of strings. For
example:
{'Serak': ('Rigel VII', 'Preparer'),
'Zim': ('Irk', 'Invader'),
'Lrrr': ('Omicron Persei 8', 'Emperor')}
If a key from the keys argument is missing from the dictionary,
then that row was not found in the table.
Raises:
IOError: An error occurred accessing the bigtable.Table object.
"""
pass
সাবপ্রসেস ম্যানেজমেন্ট ডকুমেন্টেশনের রেফারেন্স দেওয়ার স্বীকৃত উত্তর সম্পর্কে এবিবির একটি প্রশ্ন রয়েছে। আপনি যদি কোনও মডিউল আমদানি করেন তবে আপনি দ্রুত ইন্সপেক্ট.গেটসোর্সের মাধ্যমে মডিউল ডকস্ট্রিংগুলি দেখতে পাবেন।
সাইলেন্ট ঘোস্টের সুপারিশ ব্যবহার করে অজগর দোভাষী থেকে একটি উদাহরণ:
>>> import subprocess
>>> import inspect
>>> import print inspect.getsource(subprocess)
অবশ্যই আপনি সহায়তা ফাংশন মাধ্যমে মডিউল ডকুমেন্টেশন দেখতে পারেন। উদাহরণস্বরূপ সহায়তা (সাবপ্রসেস)
আমি উদাহরণস্বরূপ কাওয়ার্গের জন্য সাবপ্রসেসি ডকস্ট্রিংয়ের ব্যক্তিগতভাবে অনুরাগী নই, তবে গুগলের উদাহরণের মতো এটি স্পিঙ্কস ডকুমেন্টেশনের উদাহরণে প্রদর্শিত হিসাবে কাওয়ার্গগুলি আলাদাভাবে তালিকাভুক্ত করে না।
def call(*popenargs, **kwargs):
"""Run command with arguments. Wait for command to complete, then
return the returncode attribute.
The arguments are the same as for the Popen constructor. Example:
retcode = call(["ls", "-l"])
"""
return Popen(*popenargs, **kwargs).wait()
আমি এবিবি-র প্রশ্নের এই উত্তরটি অন্তর্ভুক্ত করছি কারণ এটি লক্ষণীয় যে আপনি কোনও কোডের মডিউসের উত্স বা ডকুমেন্টেশনগুলি এইভাবে আপনার কোড মন্তব্য করার জন্য অন্তর্দৃষ্টি এবং অনুপ্রেরণার জন্য পর্যালোচনা করতে পারেন।
other_silly_variableএটি কোনও কাওয়ার্স যুক্তি নয়, তবে সম্পূর্ণ সাধারণ।
অন্য কেউ যদি কিছু বৈধ বাক্য গঠন খুঁজছেন .. এখানে একটি উদাহরণ ডক্ট্রিং। এটি ঠিক কীভাবে আমি এটি করেছি, আমি আশা করি এটি আপনার পক্ষে কার্যকর, তবে আমি দাবি করতে পারি না যে এটি বিশেষত কোনও কিছুর সাথে সম্মতিযুক্ত।
def bar(x=True, y=False):
"""
Just some silly bar function.
:Parameters:
- `x` (`bool`) - dummy description for x
- `y` (`string`) - dummy description for y
:return: (`string`) concatenation of x and y.
"""
return str(x) + y
def foo (a, b, **kwargs):
"""
Do foo on a, b and some other objects.
:Parameters:
- `a` (`int`) - A number.
- `b` (`int`, `string`) - Another number, or maybe a string.
- `\**kwargs` - remaining keyword arguments are passed to `bar`
:return: Success
:rtype: `bool`
"""
return len(str(a) + str(b) + bar(**kwargs)) > 20
এটি আপনি যে ডকুমেন্টেশন ব্যবহার করেন তার স্টাইলের উপর নির্ভর করে তবে আপনি যদি নমপিডোক স্টাইল ব্যবহার করেন তবে এটি **kwargsব্যবহার করে নথির প্রস্তাব দেওয়া হবে Other Parameters।
উদাহরণস্বরূপ, কোর্ণিয়ান উদাহরণ অনুসরণ করুন:
def some_function(first, second="two", **kwargs):
"""Fetches and returns this thing
Parameters
----------
first : `int`
The first parameter
second : `str`, optional
The second parameter
Other Parameters
----------------
extra : `list`, optional
Extra stuff. Default ``[]``.
suplement : `dict`, optional
Additional content. Default ``{'key' : 42}``.
"""
বিশেষত নোট করুন যে কাওয়ার্গের ডিফল্ট দেওয়ার পরামর্শ দেওয়া হয়, কারণ ফাংশনের স্বাক্ষর থেকে এগুলি সুস্পষ্ট নয়।
আপনি যদি নমপিডোক স্টাইলে এটি কীভাবে করবেন তা সন্ধান করছেন , আপনি স্প্রেঞ্জ এক্সটেনশন নেপোলিয়ান এবং পান্ডাস ডকুমেন্টেশন স্প্রিন্ট 2018 এর ডাস্টস্ট্রিং গাইড থেকে নমপিডোক উদাহরণে যেমন প্রকার উল্লেখ না করেই কেবল পরামিতি বিভাগে উল্লেখ**kwargs করতে পারেন ।
আমি এর একটি উদাহরণ এখানে পেয়েছি LSST ডেভেলপার নির্দেশিকা যা খুবই ভাল ব্যাখ্যা করেন কি হওয়া উচিত বিবরণ এর **kwargsপরামিতি:
def demoFunction(namedArg, *args, flag=False, **kwargs):
"""Demonstrate documentation for additional keyword and
positional arguments.
Parameters
----------
namedArg : `str`
A named argument that is documented like always.
*args : `str`
Additional names.
Notice how the type is singular since the user is expected to pass individual
`str` arguments, even though the function itself sees ``args`` as an iterable
of `str` objects).
flag : `bool`
A regular keyword argument.
**kwargs
Additional keyword arguments passed to `otherApi`.
Usually kwargs are used to pass parameters to other functions and
methods. If that is the case, be sure to mention (and link) the
API or APIs that receive the keyword arguments.
If kwargs are being used to generate a `dict`, use the description to
document the use of the keys and the types of the values.
"""
বিকল্পভাবে, @ জোনাস অ্যাডলারের পরামর্শ অনুসারে বিল্ডিং, আমি এর বিবরণটি বিভাগে রাখা**kwargsOther Parameters আরও ভাল মনে করি - এমনকি এই উদাহরণ ম্যাটপ্ল্লোব ডকুমেন্টেশন গাইড থেকে প্রস্তাব দেয়।