fakegit · pull · Apr 3, 2020 · Apr 3, 2020 · Apr 3, 2020 · Apr 3, 2020
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,76 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+ advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+ address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+ professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team by raising an issue on GitHub. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,17 @@
+# Contributing
+
+When contributing to this repository, please first discuss the change you wish to make via issue
+here on GitHub.
+
+Please note we have a code of conduct, please follow it in all your interactions with the project.
+
+## Pull Request Process
+
+1. Ensure any install or build dependencies are removed before the end of the layer when doing a 
+   build.
+2. Update the README.md with details of changes to the interface, this includes new environment 
+   variables, exposed ports, useful file locations and container parameters.
+3. Increase the version numbers in any examples files and the README.md to the new version that this
+   Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/).
+4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you 
+   do not have permission to do that, you may request the second reviewer to merge it for you.
diff --git a/README.md b/README.md
@@ -1,8 +1,13 @@
 # pythonping
-PythonPing is simple way to ping in Python. With it, you can send ICMP Probes to remote devices like you would do from the terminal. PythonPing is modular, so that you can run it in a script as a standalone function, or integrate its components in a fully-fledged application.
+PythonPing is simple way to ping in Python. With it, you can send ICMP Probes to remote devices like
+you would do from the terminal. PythonPing is modular, so that you can run it in a script as a
+standalone function, or integrate its components in a fully-fledged application.

 ## Basic Usage
-The simplest usage of PythonPing is in a script. You can use the `ping` function to ping a target. If you want to see the output immediately, emulating what happens on the terminal, use the `verbose` flag as below.
+The simplest usage of PythonPing is in a script. You can use the `ping` function to ping a target.
+If you want to see the output immediately, emulating what happens on the terminal, use the
+`verbose` flag as below.
+
 ```python
 from pythonping import ping

@@ -16,17 +21,46 @@ Reply from 127.0.0.1, 9 bytes in 0.14ms
 Reply from 127.0.0.1, 9 bytes in 0.12ms
 Reply from 127.0.0.1, 9 bytes in 0.12ms
 ```
-Regardless of the verbose mode, the `ping` function will always return a `ResponseList` object. This is a special iterable object, containing a list of `Response` items. In each response, you can find the packet received and some meta information, like the time it took to receive the response and any error message.
+
+Regardless of the verbose mode, the `ping` function will always return a `ResponseList` object.
+This is a special iterable object, containing a list of `Response` items. In each response, you can
+find the packet received and some meta information, like the time it took to receive the response
+and any error message.
+
 You can also tune your ping by using some of its additional parameters:
 * `size` is an integer that allows you to specify the size of the ICMP payload you desire
-* `timeout` is the number of seconds you wish to wait for a response, before assuming the target is unreachable
+* `timeout` is the number of seconds you wish to wait for a response, before assuming the target
+is unreachable
 * `payload` allows you to use a specific payload (bytes)
 * `count` specify allows you to define how many ICMP packets to send
-* `sweep_start` and `sweep_end` allows you to perform a ping sweep, starting from payload size defined in `sweep_start` and growing up to size defined in `sweep_end`. Here, we repeat the payload you provided to match the desired size, or we generate a random one if no payload was provided. Note that if you defined `size`, these two fields will be ignored
+* `sweep_start` and `sweep_end` allows you to perform a ping sweep, starting from payload size
+defined in `sweep_start` and growing up to size defined in `sweep_end`. Here, we repeat the payload
+you provided to match the desired size, or we generate a random one if no payload was provided.
+Note that if you defined `size`, these two fields will be ignored
 * `df` is a flag that, if set to True, will enable the *Don't Fragment* flag in the IP header
 * `verbose` enables the verbose mode, printing output to a stream (see `out`)
-* `out` is the target stream of verbose mode. If you enable the verbose mode and do not provide `out`, verbose output will be send to the `sys.stdout` stream. You may want to use a file here, for example.
+* `out` is the target stream of verbose mode. If you enable the verbose mode and do not provide
+`out`, verbose output will be send to the `sys.stdout` stream. You may want to use a file here.
+
+## FAQ
+### Do I need privileged mode or root?
+Yes, you need to be root to use pythonping.
+
+### Why do I need to be root to use pythonping?
+All operating systems allow programs to create TCP or UDP sockets without requiring particular
+permissions. However, ping runs in ICMP (which is neither TCP or UDP). This means we have to create
+raw IP packets, and sniff the traffic on the network card.
+**Operating systems are designed to require root for such operations**. This is because having
+unrestricted access to the NIC can expose the user to risks if the application running has bad
+intentions. This is not the case with pythonping of course, but nonetheless we need this capability
+to create custom IP packets. Unfortunately, there is simply no other way to create ICMP packets.

 ## Advanced Usage
-If you wish to extend PythonPing, or integrate it in your application, we recommend to use the classes that are part of Python Ping instead of the `ping` function.
-`executor.Communicator` handles the communication with the target device, it takes care of sending ICMP requests and processing responses. It ultimately produces the `executor.ResponseList` object. The `Communicator` needs to know a target and which payloads to send to the remote device. For that, we have several classes in the `payload_provider` module. You may want to create your own provider by extending `payload_provider.PayloadProvider`. If you are interested in that, you should check the documentation of both `executor` and `payload_provider` module.
+If you wish to extend PythonPing, or integrate it in your application, we recommend to use the
+classes that are part of Python Ping instead of the `ping` function. `executor.Communicator` 
+handles the communication with the target device, it takes care of sending ICMP requests and 
+processing responses. It ultimately produces the `executor.ResponseList` object. The `Communicator`
+needs to know a target and which payloads to send to the remote device. For that, we have several
+classes in the `payload_provider` module. You may want to create your own provider by extending
+`payload_provider.PayloadProvider`. If you are interested in that, you should check the
+documentation of both `executor` and `payload_provider` module.
diff --git a/pythonping/network.py b/pythonping/network.py
@@ -4,10 +4,9 @@


 class Socket:
-    BUFFER_SIZE = 1024
    DONT_FRAGMENT = (socket.SOL_IP, 10, 1)           # Option value for raw socket

-    def __init__(self, destination, protocol, source=None, options=()):
+    def __init__(self, destination, protocol, source=None, options=(), buffer_size=2048):
        """Creates a network socket to exchange messages

        :param destination: Destination IP address
@@ -17,9 +16,15 @@ def __init__(self, destination, protocol, source=None, options=()):
        :param options: Options to set on the socket
        :type options: tuple
        :param source: Source IP to use - implemented in future releases
-        :type source: Union[None, str]"""
-        self.destination = socket.gethostbyname(destination)
+        :type source: Union[None, str]
+        :param buffer_size: Size in bytes of the listening buffer for incoming packets (replies)
+        :type buffer_size: int"""
+        try:
+            self.destination = socket.gethostbyname(destination)
+        except socket.gaierror as e:
+            raise RuntimeError('Cannot resolve address "' + destination + '", try verify your DNS or host file')
        self.protocol = socket.getprotobyname(protocol)
+        self.buffer_size = buffer_size
        if source is not None:
            raise NotImplementedError('PythonPing currently does not support specification of source IP')
        self.socket = socket.socket(socket.AF_INET, socket.SOCK_RAW, self.protocol)
@@ -49,7 +54,7 @@ def receive(self, timeout=2):
            if not data_ready[0]:
                # Timeout
                return b'', '', time_left
-            packet, source = self.socket.recvfrom(self.BUFFER_SIZE)
+            packet, source = self.socket.recvfrom(self.buffer_size)
            return packet, source, time_left

    def __del__(self):

diff --git a/setup.py b/setup.py
@@ -4,7 +4,7 @@
    long_description = file.read()

 setup(name='pythonping',
-      version='1.0.8',
+      version='1.0.9',
      description='A simple way to ping in Python',
      url='https://github.com/alessandromaggio/pythonping',
      author='Alessandro Maggio',

diff --git a/test/test_network.py b/test/test_network.py
@@ -0,0 +1,11 @@
+import unittest
+from pythonping.network import Socket
+
+
+class UtilsTestCase(unittest.TestCase):
+    """Tests for Socket class"""
+
+    def test_raise_explicative_error_on_name_resolution_failure(self):
+        """Test a runtime error is generated if the name cannot be resolved"""
+        with self.assertRaises(RuntimeError):
+            Socket('cant.resolve.this.address.localhost', 'ip')